Adapters vs Plugins in KickJS v5 — Choosing the Right Primitive

#kickjs #typescript #node #architecture

You read the adapters article. You understood defineAdapter. You went to wire up your next concern, opened the v5 docs, and got hit with a second word: definePlugin. The shapes look almost identical — both take a name, both can return middleware(), both can register DI tokens, both can contribute context decorators. Hovering the types in your editor only deepens the question:

"I just need to register a service. defineAdapter or definePlugin?"

This article is the answer. Short version: the surfaces overlap because they were designed to. The difference is identity, lifecycle, and distribution — not capability. Once you internalize that, the choice becomes mechanical.

What an adapter actually is

An adapter is a piece of app-level infrastructure that owns long-lived resources and plugs into the bootstrap lifecycle. The first article covered the lifecycle in depth; the short version is that an AppAdapter is a typed object the framework calls in a fixed order: beforeMount → beforeStart → middleware() collected → onRouteMount per controller → afterStart → (requests served) → shutdown on SIGTERM.

The mental model is "the bootstrap machinery composes a fleet of these, in order, exactly once per process." Adapters are single-instance by identity. A typical app has one DB-pool adapter, one mailer adapter, one observability adapter — they own resources nobody else should own (connection pools, tracer SDKs, mail transports). Two of any of them would mean two pools, which is almost always a bug.

Adapters are also declared at the application layer. They live next to bootstrap() because they know things only the application knows: which env vars matter, which secrets provider to use, which cluster URL to dial. They aren't packaged for redistribution because they aren't generic — they are this app's infrastructure.

The shape, in miniature:

const dbAdapter = defineAdapter<{ url: string }>({
  name: 'DbAdapter',
  build(config) {
    return {
      async beforeStart({ container }) {
        const pool = await createPool(config.url)
        container.registerInstance(DB, pool)
      },
      async shutdown() { /* drain pool */ },
    }
  },
})

Every lifecycle hook is on the table. Resources you create in beforeStart you tear down in shutdown. That symmetry is the whole point of the primitive.

What a plugin actually is

A plugin is a reusable building block packaged for redistribution. It can ship modules, adapters, middleware, contributors, and DI bindings, and an app opts in by passing it to bootstrap({ plugins: [...] }). The shape is intentionally similar to an adapter's, but the framing is different: a plugin is a bundle that travels — across apps, across teams, often as an npm package.

In its smallest form:

const RateLimitPlugin = definePlugin<{ rps: number }>({
  name: 'RateLimitPlugin',
  build(config) {
    return {
      register(container) { container.registerInstance(LIMITS, config) },
      middleware() { return [rateLimitMiddleware(config)] },
    }
  },
})

A plugin can also expose an adapters() slot — a common pattern for "give me the whole subsystem in one import." Three properties matter:

Opt-in registration. Adapters live in the app's adapter array; plugins live in the app's plugins array. The plugins array is the shape that travels in README snippets — bootstrap({ plugins: [RateLimitPlugin({ rps: 50 })] }).
Multiple per app are normal. An app can pull in observability, CORS, MFA, rate-limiting, and feature-flag plugins side by side. They run before the application bootstraps proper, in dependsOn-aware order.
Designed for redistribution. definePlugin carries a version, a requires.kickjs peer-version, and a defaults config slot — all the surface a published npm package needs to declare compatibility and let consumers override config.

A plugin doesn't have to be published — in-repo plugins are fine — but the design choices make sense only when you read them as "what do I need so a stranger can npm install this and bootstrap it?"

Decision matrix

Walk these in order. The first row that fits is your answer.

Is it the application's own infrastructure (DB pool, secrets, observability, mailer transport, tenant resolver)? → adapter. It belongs next to bootstrap() with the rest of the app's wiring.
Does it own a long-lived resource that needs beforeStart to construct and shutdown to drain? → adapter. The lifecycle was built for this.
Should there be exactly one in the process, ever? → adapter. Two infrastructure adapters in the same app means two of whatever the adapter owns — usually a bug.
Is it generic enough that another team or app could plausibly use it unchanged? → plugin. Even if you keep it in-repo today, model it as a plugin so the move-out cost is zero.
Does it bundle a module + DI registration + (maybe) an adapter into one import? → plugin. The adapters() slot exists for exactly this.
Will it ship as an npm package, with its own version and a requires.kickjs range? → plugin. The definePlugin shape is an npm-package surface.
Will multiple consumers configure it differently (different keys, transports, rules)? → plugin. The defaults + caller-overrides story is built for opt-in callers passing config.

The rule of thumb: adapters are nouns this app owns; plugins are nouns this app installs. If you're hesitating, ask "could I npm publish this tomorrow and have it make sense to someone who has never seen our codebase?" If yes, plugin. If the answer is "no, this only makes sense given our env, our DB, our secrets layout," adapter.

Walkthrough — when a mailer is an adapter

Picture an app that needs to send transactional email. It picks a provider (SES, Postmark, console-logging in dev), configures a default sender, and exposes a MailerService to the rest of the codebase. You could package this as a plugin. Most of the time you shouldn't — adapter form is the better fit.

A sketch of the adapter form:

const MailerAdapter = defineAdapter<{ provider: MailProvider; from: Address }>({
  name: 'MailerAdapter',
  build(config) {
    return {
      beforeStart({ container }) {
        container.registerInstance(MAILER, new MailerService(config))
      },
    }
  },
})

Three things make this an adapter, not a plugin:

Single-instance by identity. The app has exactly one MailerService. The MAILER token is registered once. Two mailer adapters would clash on the token and double-bill the SMTP transport.
App-level composition. The default sender address is this app's identity. The provider choice (console in dev/test, real transport in prod) is this app's environment story. None of that travels.
No redistribution case. "A MailProvider plus a thin service that picks one based on config" is roughly ten lines per consumer. Anybody else writing a v5 app would write their own adapter the same way. The plugin shape (versioning, peer range, defaults-merging, npm packaging) would be ceremony with no payoff.

Plugin form would become appropriate the moment you wanted to ship a sender, retry policy, templating engine, and provider matrix as a packaged unit — at that point the bundle has its own version, its own peer-version range, and its own consumers. Until then, a small adapter wins on every axis.

Walkthrough — when a feature wants to be a plugin

Now picture a second-factor auth feature: issue a TOTP secret, verify a one-time code, recover via backup codes. It's a different shape entirely, and adapter form would fight you the whole way.

A sketch of the plugin form:

const TotpPlugin = definePlugin<{ encryptionKey: string }>({
  name: 'TotpPlugin',
  build(config) {
    return {
      register(container) { container.registerInstance(CIPHER, makeCipher(config)) },
      modules() { return [TotpModule] },
    }
  },
})

Why is this a plugin?

It's a bundle, not a single piece of infrastructure. It ships a module (controllers + routes), DI tokens (a secret cipher, repos), and a config surface (the encryption key). The plugin shape was designed precisely for "give me the whole subsystem in one import." Adapter form would force splitting these into separate registrations on the application side.
The encryption key is consumer-supplied configuration. A plugin's defaults plus caller-overrides ergonomics fit this naturally. Different apps pass different keys, which is exactly the "config is opt-in" story.
It's pre-built for redistribution. Maybe today it has one consumer. The cost of plugin form (one more workspace package) is small; the cost of not doing it and later having to repackage during a real rollout is much larger. Plugin form is cheap insurance.
It composes with dependsOn. Plugins participate in topological sort. If a future MFA-enforcement plugin needs to mount after TOTP, it just declares dependsOn: ['TotpPlugin'].

That last point is the tell. Anything that might be one of several peer building blocks — auth methods, instrumentation backends, rate-limit strategies — wants to be a plugin so the next sibling can compose with it cleanly.

Both can register middleware and contributors

The two registration surfaces overlap on purpose. Adapters can middleware(); plugins can middleware(). Adapters can contributors(); plugins can contributors(). Adapters can register DI bindings (in beforeStart); plugins can register DI bindings (in register). The framework even merges contributors at the same 'adapter' precedence level for both — a plugin is a cross-cutting bundle, narrower than the global default but broader than a per-module hook, and that places it on the same precedence band as adapter-supplied contributors.

This equivalence is deliberate. The capabilities are kept symmetric so you don't pick the wrong primitive and discover three weeks later it can't do something. The decision is identity, lifecycle ownership, and distribution — not features. Pick adapter for app-level infrastructure with a single owner. Pick plugin for portable bundles meant to be configured and reused.

A useful litmus test

When you're stuck, write the README snippet you'd want a future consumer to paste. If it reads naturally as:

bootstrap({ plugins: [MyThing({ key: '...' })] })

…and the key: '...' makes sense as something callers override — you're holding a plugin. If instead the only sensible call site is your own app's adapter file, with config pulled from your own env, and there's no plausible second consumer — you're holding an adapter. Don't fight the shape. The two primitives exist precisely so each kind of concern has a home that fits.