KickJS v5 におけるアダプターとプラグイン：適切なプリミティブを選択する

アダプターの記事を読み、defineAdapter を理解した。次に次の課題を繋げるために v5 のドキュメントを開いたところ、二番目の単語に遭遇した。definePlugin。その形状はほぼ同一だ。どちらも名前を受け取り、どちらも middleware() を返せる、どちらも DI トークンを登録できる、どちらもコンテキスト装飾者を寄与できる。エディタで型をホバーするだけで疑問は深まる：「単にサービスを登録するだけだ。defineAdapter か definePlugin か？」。この記事に答えがある。短縮版：表面は重なるが、それは設計されたからだ。違いは機能ではなく、アイデンティティ、ライフサイクル、そして配布にある。それらを内面化すれば、選択は機械的になる。アダプターは長持ちするリソースを所有し、ブートストラップのライフサイクルに接続するアプリケーションレベルのインフラストラクチャの一部である。最初の記事でライフサイクルを詳細に説明したが、短縮版では AppAdapter はフレームワークが固定順序で呼ぶ型付けされたオブジェクトである：beforeMount → beforeStart → middleware() の収集 → コントローラーごとの onRouteMount → afterStart → (リクエスト処理完了) → shutdown on SIGTERM。モデルは「ブートストラップ機械がこれらを 1 プロセスあたりちょうど 1 回ずつ順次構成する」である。アダプターはアイデンティティが単一インスタンスである。典型的なアプリケーションには 1 つの DB プールアダプター、1 つのメールアダプター、1 つの観測可能化アダプターがある。それらのリソースを他の誰も所有するべきではない（接続プール、トレース SDK、メールトランスポーティング）。それらが 2 つあるということは、これは常にバグである。アダプターはアプリケーション層で宣言される。それらは bootstrap() の隣に存在し、アプリケーションのみが知っていることを知っている：どの環境変数が重要か、どのシークレットプロバイダーを使うか、どのクラスター URL を接続するか。それらは再配布用にはパッケージ化されない。汎用的ではないからだ。それらはそのアプリケーションのインフラストラクチャである。形状のミニマル版： 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() { /* プール排他 */ }, } }, }) ライフサイクルのすべてのフックがテーブルにある。beforeStart で作成したリソースは shutdown で破壊される。その対称性がプリミティブの要点である。 プラグインは再配布用にパッケージ化された再利用可能なビルディングブロックである。モジュール、アダプター、ミドルウェア、コントリビューター、そして DI 結合を発送でき、アプリケーションはそれらを bootstrap({ plugins: [...] }) に渡すことでオンボーダーできる。形状はアダプターと意図的に類似しているが、枠組みは異なる。プラグインは渡り鳥のバンドルである：アプリケーション間、チーム間を旅し、しばしば npm パッケージとして。最小形式： const RateLimitPlugin = definePlugin<{ rps: number }>({ name: 'RateLimitPlugin', build(config) { return { register(container) { container.registerInstance(LIMITS, config) }, middleware() { return [rateLimitMiddleware(config)] }, } }, }) プラグインはまた adapters() スロットを公開できる。これは「1 インポートでサブシステムを全部を与えよ」という一般的なパターンである。3 つの性質が決定的である。オンボーダー登録。アダプターはアプリケーションのアダプター配列に存在する。プラグインはアプリケーションのプラグイン配列に存在する。プラグイン配列が README のスニペットで旅する形状である—bootstrap({ plugins: [RateLimitPlugin({ rps: 50 })] })。1 つ以上のプラグインは通常である。アプリケーションは観測可能化、CORS、MFA、レート制限、そして機能フラグのプラグインを並行して引き込める。それらはアプリケーションが正常にブートストラップされる前に、依存関係認識の順序で実行される。再配布に設計された。definePlugin はバージョン、requires.kickjs パーピアバージョン、そしてデフォルト設定スロットを運び、これらは発表された npm パッケージが必要とする表面である。互換性を宣言し、消費者が設定を上書きすることを許可する。プラグインは発表されていなくてもよい。リポジトリ内のプラグインは問題ないが、設計の選択は「不審者が npm install これしだいブートストラップできるようには何を必要とするか」と読むときに意味を持つ。順序でこれらを歩く。適合する最初の行があなたの答えである。それはアプリケーション自身のインフラストラクチャか（DB プール、シークレット、観測可能化、...）

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. 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. 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?" 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. 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. 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. 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. 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. KickJS framework on GitHub KickJS docs — plugins guide KickJS docs — adapters guide @forinda/kickjs on npm