DEV Community: Orinda Felix Ochieng

Building Custom Context Decorators in KickJS

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:50:09 +0000

In Express you reach for req.locale = ... inside a middleware and hope the
downstream handler remembers what type it is. KickJS gives you a better home
for that data: a context decorator. You declare the key once, write a
typed resolve(ctx) function, register it at the scope it belongs to, and
every handler in that scope can call ctx.get('locale') with full type
safety. Anything you'd hang off req — request id, locale, the audit actor,
feature flags, an idempotency key — should live here instead. This article
is the field guide: the two factories, the full options surface, the five
registration scopes and how they fight, how to read values back from
handlers and services, the boot-time errors you should know on sight, and
three patterns worth stealing.

The two factories

KickJS ships two factories, and the difference is whether your resolver
needs to see the HTTP request.

defineHttpContextDecorator is for HTTP routes. The ctx argument it hands
your resolver is a RequestContext — ctx.req, ctx.headers, ctx.params,
ctx.body, plus the shared get/set/requestId surface. Reach for it
when the value is derived from the wire: parsing an Accept-Language
header, lifting an X-Idempotency-Key, decoding a cookie, anything that
only makes sense in the HTTP transport.

defineContextDecorator is transport-agnostic. The ctx it gives you is
an ExecutionContext with only get, set, and requestId — no req,
no headers. That's deliberate: a contributor built on this factory will
also work the same way inside a CLI command, a queue worker, a cron job,
or whatever non-HTTP transport adapter you bolt on next. Reach for it when
the value is computed from other context entries (dependsOn) or from DI
services (deps), not from the request itself. A LoadFeatureFlags
contributor that takes the resolved actor id from dependsOn and asks a
flag service is a perfect fit — it doesn't care whether the call came in
over HTTP.

The rule of thumb: start with defineContextDecorator and only escalate
to the HTTP variant if your resolver actually touches ctx.req. Keeping
contributors transport-agnostic where you can means the day you mount the
same module under a queue worker, every contributor still works.

The options surface

Both factories take the same options object. Six fields, each pulling its
weight.

export const LoadLocale = defineHttpContextDecorator({
  key: 'locale',
  deps: [LocaleService] as const,
  dependsOn: ['actor'],
  optional: false,
  onError: (_err, _ctx) => 'en',
  resolve: (ctx, [locales]) => {
    const actor = ctx.get('actor');
    return locales.resolveFor(actor, ctx.headers['accept-language']);
  },
});

key is the string handle the rest of the system uses to find this value. It's also the field you'll augment in ContextMeta for type safety. Pick something stable — renaming a key is a breaking change for every handler that reads it.
resolve(ctx, deps?) is the work itself. Sync or async, returns the value to be stored under key. Throwing here is a real error unless optional or onError says otherwise.
deps is a tuple of DI tokens. Whatever you list shows up as the second argument to resolve, already constructed and scoped to the current request. Mark it as const so the tuple types survive into the argument signature.
dependsOn declares which other context keys must be resolved before this one runs. KickJS topologically sorts contributors at boot and guarantees the order. If you read ctx.get('actor') inside resolve, put 'actor' in dependsOn — otherwise you're racing.
optional: true swallows resolver errors silently. The key simply ends up undefined. Use it for genuinely optional signals (a missing idempotency header is fine; a missing tenant probably isn't).
onError(err, ctx) is the recovery hatch. If resolve throws and onError is defined, its return value gets stored under key. Use it for sane defaults — a failed locale lookup falling back to 'en', a missing feature-flag service falling back to an empty set.

Five places to register a contributor

A decorator definition is inert until you register it somewhere. KickJS
offers five scopes, and they form a strict precedence chain:

Method > Class > Module > Adapter > Global.

Method — @LoadLocale() placed on a single handler. Highest precedence; a route-specific override that beats every wider scope.
Class — @LoadLocale() on a controller class. Applies to every handler on that controller. The right scope when a single resource is the only thing that needs the value.
Module — return it from AppModule.contributors?(). Every route the module mounts gets it. Best for module-domain values that don't belong to the whole app.
Adapter — return it from AppAdapter.contributors?(). Every route in the app gets it. This is where cross-cutting concerns (request id, trace context, the actor lookup) belong.
Global — pass it via bootstrap({ contributors: [...] }). App-wide defaults, lowest precedence — anything below can override.

The precedence rule does two different things depending on whether the
collision is at the same level or across levels.

Same level, same key: KickJS throws DuplicateContributorError at
boot. Two adapter-level contributors both producing 'locale' is a bug,
not a configuration question, and the framework refuses to guess. Pick
one.

Cross level, same key: the higher-precedence one silently wins. A
method decorator beats a class decorator beats a module contributor beats
an adapter contributor beats a global one. No warning, no error — that's
the point of overrides. Define LoadLocale adapter-wide as the default,
then attach a LoadLocale({ source: 'query' }) method-level decorator on
the one admin route that wants the locale taken from ?locale= instead
of headers, and the override happens cleanly.

A useful mental model: register where the responsibility actually
lives. Cross-cutting concerns belong on the adapter. Module-domain
values belong on the module. One-off overrides belong on the method.
Global is for defaults you'll let any of the above replace.

Reading the value back

Inside a handler you have ctx, so it's just ctx.get(key):

@Controller('/orders')
export class OrdersController {
  @Get('/')
  list(@RequestCtx() ctx: RequestContext) {
    const locale = ctx.get('locale'); // typed via ContextMeta
    return this.orders.list(locale);
  }
}

Inside a service — somewhere with no ctx in scope — you reach for the
async-local-storage helpers:

import { getRequestValue, getRequestStore } from '@forinda/kickjs';

export class OrdersService {
  list() {
    const locale = getRequestValue<string>('locale'); // T | undefined
    const { requestId } = getRequestStore();          // throws outside a request
    this.log.info({ requestId, locale }, 'listing orders');
  }
}

getRequestValue is the safe one — returns T | undefined, fine to call
anywhere. getRequestStore throws if there's no active request frame, so
use it only when you're certain you're inside one (a request handler, a
service called from one). The async-local-storage backing means it works
through await boundaries without you threading ctx everywhere.

Errors and recovery

Two boot-time errors are worth recognizing on sight:

MissingContributorError — a contributor declares dependsOn: ['actor'] but no contributor in the resolved chain produces 'actor'. Thrown at boot, before any request is served. Fix: register the missing contributor or remove the dependency.
ContributorCycleError — A depends on B, B depends on A. Also thrown at boot. Fix: break the cycle, usually by extracting the shared piece into a third contributor both depend on.

At request time, optional and onError are your two recovery levers.
optional: true says "if this fails, just leave the key undefined and
keep going." onError says "if this fails, here's the value to use
instead." Reach for optional when downstream code already handles
undefined; reach for onError when there's a meaningful default.

Three patterns worth stealing

Per-route override. Define an adapter-level LoadLocale that reads
Accept-Language. On the one admin route that takes ?locale= from the
query string, attach a method-level @LoadLocale({ source: 'query' }).
The method scope beats the adapter scope silently — no if branches in
the resolver, no flags, just precedence doing the work.

Plugin-shipping. When you publish a contributor as part of a library,
export both the @DecoratorName form and the underlying .registration
object. Consumers who want it on every route call bootstrap({ contributors: [LoadFeatureFlags.registration] }). Consumers who want it
on a single controller use @LoadFeatureFlags(). Same definition, both
ergonomics.

export const LoadFeatureFlags = defineContextDecorator({
  key: 'flags',
  deps: [FlagsService] as const,
  resolve: (_ctx, [flags]) => flags.snapshot(),
});
// Consumers reach for either LoadFeatureFlags() or LoadFeatureFlags.registration.

Factory wrapper for parameterized decorators. When the same
contributor needs different config per call site, wrap the factory in a
function:

export const LoadRequestStartedAt = (clock: () => number = Date.now) =>
  defineContextDecorator({
    key: 'requestStartedAt',
    resolve: () => clock(),
  });

Now LoadRequestStartedAt() uses the real clock, LoadRequestStartedAt(() => 0) is trivially mockable in tests, and the type signature stays clean.

A note on type safety

ctx.get('locale') returns unknown until you augment the type. Drop
this once per key, in a .d.ts file or near the contributor definition:

declare module '@forinda/kickjs' {
  interface ContextMeta {
    locale: string;
    requestStartedAt: number;
    flags: ReadonlySet<string>;
  }
}

After that every ctx.get is fully typed. There's a separate article on
the augmentation mechanics — the short version is: yes, do it, every key,
every time.

Testing

Unit-test the resolver in isolation. Mock its deps, hand it a stub ctx
with the dependsOn keys pre-seeded via set, assert the return value.
That's it — no app boot, no HTTP, no DI container.

Integration-test by booting the real adapter through createTestApp and
hitting it with supertest. The contributor chain runs end-to-end and you
verify what handlers actually see.

For service-layer reads — code that calls getRequestValue or
getRequestStore — wrap the assertion in a requestStore.run frame:

requestStore.run(
  { requestId: 'test', instances: new Map(), values: { locale: 'fr' } },
  () => expect(service.preferredLocale()).toBe('fr'),
);

That's the same async-local-storage backing the framework uses at
runtime, so the production code path runs unchanged.

References

The KickJS Lifecycle — Bootstrap, Runtime, Shutdown

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:47:24 +0000

Every framework has a lifecycle, but most leave you to reverse-engineer it from console logs and stack traces. KickJS is unusually explicit about its phases — there are three of them, the firing order inside each is documented, and the framework will throw at boot if you wire up something that violates the contract. That clarity is a feature: it means you can pick the right hook the first time instead of discovering at 2am that your DB pool was constructed before the config adapter had loaded its env vars. This article walks the three phases, the ordering rules inside each, and the contracts you can rely on at each step.

The three phases

A KickJS process has exactly three phases, and they happen in this order:

Setup — everything that runs once during bootstrap(). Config loads, adapters mount, modules register, routes are wired, listen() fires. By the end of this phase, the app is accepting connections.
Runtime — the per-request phase. For every inbound HTTP request, a fresh AsyncLocalStorage frame is opened, middleware and contributors run, the handler resolves, and the frame closes. This phase repeats indefinitely.
Shutdown — triggered by SIGTERM, SIGINT, or an explicit app.shutdown() call. Every adapter's shutdown() runs concurrently, the HTTP server closes, and the process exits.

Setup runs once. Runtime runs N times. Shutdown runs once. Knowing which phase you're in tells you which APIs are safe to call.

The setup phase, step by step

The setup phase has a deterministic firing order. Here it is end to end:

bootstrap()
  │
  ├─ 1. Adapter beforeMount hooks      (config / env adapters resolve here)
  ├─ 2. Hardened defaults + ALS frame  (request-scope is now installable)
  ├─ 3. Adapter middleware mount       (beforeGlobal → afterGlobal
  │                                     → beforeRoutes → afterRoutes)
  ├─ 4. Plugin + user middleware       (in registration order)
  ├─ 5. Security defaults              (helmet, CORS, body limits)
  ├─ 6. Module registration            (DI registry populated)
  ├─ 7. Route mounting                 (per-controller onRouteMount fires)
  ├─ 8. Adapter beforeStart hooks      (every route is known, listen() is not)
  ├─ 9. server.listen()                (socket bound, accepting connections)
  └─ 10. Adapter afterStart hooks      (announce, register with discovery, etc.)

A few things are worth pinning down at each step.

By the time step 1 finishes, anything an adapter wanted to read from the environment or from a config file is loaded. This is where a config adapter's beforeMount parses .env and exposes typed values. Until this step completes, do not assume any config is present.

By step 2, the AsyncLocalStorage substrate is installed but no request frame exists yet — there's nothing to scope to. Code that calls getRequestContext() here will (correctly) get undefined.

Steps 3–5 layer middleware. The four-phase model — beforeGlobal, afterGlobal, beforeRoutes, afterRoutes — gives adapters a predictable place to inject cross-cutting concerns: a tracing adapter wraps everything in beforeGlobal; an auth adapter slots in at beforeRoutes; a response-shaping adapter cleans up at afterRoutes.

By step 6, the DI registry is fully populated. Every @Service is constructible. Every registerInstance(...) call has run. This is the earliest point where you can reliably resolve dependencies by token.

Step 7 is where each controller's onRouteMount notification fires — useful for adapters that want to introspect or decorate the route table.

Step 8 — beforeStart — is the most useful and most often misused hook. Every module has registered, every route is mounted, but listen() has not yet fired. This is the right slot for "construct + register in DI" code that needs the route table populated: schema generators, OpenAPI emitters, route-conditional health checks. It is the wrong slot to start accepting external traffic — the socket isn't open yet.

By step 10 — afterStart — the server is live. This is where you announce yourself to a service registry, log the bound port, or warm a cache that depends on the app being reachable.

Within-phase ordering

Two ordering rules apply inside setup, and they answer most "why did X run before Y?" questions.

Adapters run in the order they appear in the adapters array. If you put loggingAdapter before authAdapter in your bootstrap config, logging's beforeMount runs first, its beforeGlobal middleware runs first, its beforeStart runs first, and so on. The array is the source of truth — there's no hidden priority.

Contributors are topologically sorted. A contributor is anything that adds behavior to the request pipeline — a middleware, an interceptor, a guard. KickJS sorts them at boot using a fixed precedence — method > class > module > adapter > global — so a method-scoped guard always runs inside a class-scoped one, and both run inside any global middleware. On top of that, contributors can declare an explicit dependsOn list. The framework validates the resulting graph at boot: cycles throw, missing dependencies throw, ambiguous orderings throw. You find out before listen() fires, not under load.

// Synthetic — declares "rate-limit must run after auth"
defineContributor({
  name: 'rate-limit',
  dependsOn: ['auth'],
  scope: 'global',
  run: async (ctx, next) => { /* ... */ await next(); },
});

The combination — array order for adapters, topo-sort for contributors — gives you predictable composition without surprise re-ordering.

Runtime: the per-request frame

Once the server is listening, every request goes through the same shape.

A request lands. KickJS opens a new AsyncLocalStorage frame for it — a per-request "bag" that follows every await boundary inside the handler. The middleware chain runs. The contributor pipeline runs in topo-sorted order. The matched route handler runs. The response is written. The frame closes.

There are three layers that share this bag:

@Middleware decorators — your own middleware, mounted in step 4 of setup.
The contributor wrapper — adapter and module contributors, sorted by precedence and dependsOn.
The main handler — the controller method itself.

All three see the same ctx. Anything one layer puts there with ctx.set('userId', id) is visible to the next layer with ctx.get('userId'). The bag is strictly per-request: no other concurrent request can read it, even on the same Node thread, because AsyncLocalStorage isolates it for you. That is what makes "current user", "current tenant", "current trace span" safe to store without threading them through every function signature.

// Synthetic — three layers, one bag
ctx.set('tenantId', resolveTenant(req)); // middleware
const span = ctx.get('span');             // contributor reads it
return service.list(ctx.get('tenantId')); // handler reads it

Shutdown: parallel and best-effort

When SIGTERM or SIGINT arrives — or your code calls app.shutdown() — KickJS runs every adapter's shutdown() method concurrently, wrapped in Promise.allSettled. Two properties fall out of that choice:

Concurrent. Adapters do not block each other. A slow database adapter draining its connection pool does not delay a fast logging adapter from flushing its buffer.
Failure-isolated. If one adapter's shutdown() rejects, the others still complete. allSettled never short-circuits. You will see the rejection in the framework's shutdown report, but it cannot starve siblings.

This matters for resource ownership. Each adapter is responsible for the resources it opened: the DB adapter closes its pool, the queue adapter drains its consumers, the cache adapter flushes pending writes. Nobody else cleans up for you, and nobody else's failure prevents you from cleaning up. The contract is "every adapter gets a chance."

After all shutdown() promises settle, the HTTP server closes its listener and the process exits. If you need a hard deadline, wrap your individual shutdown() body in its own timeout — the framework intentionally does not impose one.

HMR: the dev-mode caveat

In development, kick dev runs the app under Hot Module Replacement. When you save a file, the running app is torn down and re-bootstrapped — the full shutdown phase fires, then the full setup phase runs again, in the same Node process.

This is where adapters that own connections, sockets, file watchers, or background timers earn their keep. If your adapter's shutdown() doesn't actually drain — if it leaves a Postgres pool open, a Redis subscription connected, an interval ticking — you will leak those handles every time you save a file. Ten saves later your dev box has fifty zombie Postgres connections and you're staring at "too many clients" errors that don't exist in production.

The rule: write shutdown() as if it runs every five seconds, because in dev mode it effectively does. See the framework's separate HMR guide for the full reload protocol and the patterns for hot-swappable state.

App-scoped vs request-scoped state

The mental model is simple, and it's the single thing most worth internalizing.

App-scoped state lives in the DI container. It's registered once, during setup. A registerInstance(DbPoolToken, pool) call survives every request the process ever serves. Singletons, config objects, connection pools, cache clients, metric emitters — all app-scoped. They outlive any one request.

Request-scoped state lives in the AsyncLocalStorage bag. Anything you put there with ctx.set('key', value) exists only for that request and is invisible to any other concurrent request. Current user, current tenant, current trace span, current locale — all request-scoped. They die when the response is written.

If you find yourself reaching for a global mutable variable to share state between layers, you almost certainly want the bag. If you find yourself reconstructing the same object for every request, you almost certainly want DI. Get this distinction right and most of your "where does this go?" questions answer themselves.

References

KickJS Asset Manager — Type-Safe File Resolution from Dev to Dist

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:45:29 +0000

There is a familiar little discomfort that shows up the first time a Node.js service needs to read something off disk that is not source code. An email template. A JSON schema. A seed fixture. A vendored PDF. The first version is always a one-liner: fs.readFile(path.join(__dirname, '../templates/welcome.ejs')). That works on your laptop. It also works in CI. And then you ship to production, your bundler flattens the output, __dirname points at dist/handlers/ instead of src/handlers/, the relative climb misses the templates directory, and the first user who triggers a password reset gets a 500.

The pragmatic fix is to scatter process.env.NODE_ENV === 'production' ? '../../dist/templates' : '../templates' across the codebase. The principled fix is to admit that on-disk assets are a build-time concern that deserves its own little type system. That is what the KickJS Asset Manager is.

The shape of the problem

Server-side asset resolution has three properties that conspire against you.

First, the path differs between dev and dist. Dev runs against src/, dist runs against a built output that may have a different layout, possibly minified, possibly bundled, possibly emitted by a different tool than the one that compiled your handlers.

Second, the keys are stringly-typed. readFile('templates/welcome.ejs') is just a string. Rename the file, forget to update the call site, and TypeScript gives you nothing — you find out at runtime, usually from a Sentry alert, usually from an end user.

Third, the cleanup story is bad. NODE_ENV checks, try/catch fallbacks, conditional __dirname math, helper functions that paper over the asymmetry — every codebase with on-disk assets accretes a small graveyard of these. They are correct individually and incoherent collectively.

The Asset Manager replaces all three problems with a single mental model: at build time, every asset you care about is copied into a known location and recorded in a manifest. At runtime, you address those assets through a typed proxy whose shape is generated from the manifest. There is no NODE_ENV, no __dirname arithmetic, and no string keys that the compiler cannot check.

The mental model: a manifest plus a typed proxy

Two artifacts do the heavy lifting.

The first is .kickjs-assets.json, a manifest emitted into dist/ during build. It is the canonical answer to "where, on this filesystem, is the asset named mails.welcome?". It is a flat JSON object — categories at the top level, slugs underneath, absolute or dist-relative paths as values.

The second is .kickjs/types/assets.d.ts, a generated declaration file that augments the framework-supplied KickAssets interface. The interface mirrors the manifest's shape exactly: KickAssets['mails']['welcome'] exists if and only if the manifest has an entry for mails.welcome. That augmentation is what gives the proxy its types.

The runtime side is a Proxy (or several flavours of one — see below). When you write assets.mails.welcome(), the proxy walks the path ['mails', 'welcome'], looks the slug up in the manifest, and returns the resolved file path. No filesystem reads, no environment checks, no path.join math in your handlers.

The result is that asset resolution becomes a pure function from a typed key to a string path, and every typo is a compile error.

The four ways to consume an asset

KickJS gives you four consumption patterns. They all resolve through the same manifest — the difference is purely ergonomic.

1. The ambient nested proxy

The default and most common pattern. Import once, address anywhere.

import { assets } from '@forinda/kickjs';

const path = assets.mails.welcome();
const html = await renderEjs(await readFile(path, 'utf8'), { user });

assets is a deeply-nested proxy whose shape comes from the augmented KickAssets interface. IDE autocomplete works at every level: assets. shows categories, assets.mails. shows slugs.

2. `useAssets()` — the hook factory

Sometimes you want the resolver as a value, not a singleton. useAssets() returns the same proxy but as a factory call, which is convenient when you want to swap implementations in tests or pass the resolver through a DI container.

import { useAssets } from '@forinda/kickjs';

class MailService {
  constructor(private readonly assets = useAssets()) {}
  welcome() { return this.assets.mails.welcome(); }
}

This is the form to reach for when you would otherwise be tempted to mock the import.

3. `@Asset()` — the class field decorator

For class-based services where you want the resolution to be lazy and declarative.

import { Asset } from '@forinda/kickjs';

class MailService {
  @Asset('mails/welcome') private welcomeTpl!: string;

  async send(user: User) {
    const html = await renderEjs(await readFile(this.welcomeTpl, 'utf8'), { user });
  }
}

The decorator installs a getter that resolves on first access. The string argument is type-checked against the manifest, so @Asset('mails/does-not-exist') is a compile error.

4. `resolveAsset()` — the dynamic escape hatch

When the key really is dynamic — an admin choosing a template at runtime, a feature-flagged variant — fall back to the function form.

import { resolveAsset } from '@forinda/kickjs';

const path = resolveAsset('mails', slug); // slug: string

You lose the per-key compile-time check, but the category is still typed and a missing slug throws a meaningful runtime error rather than returning a bogus path.

Build → manifest → runtime

The split between build and runtime is what makes the whole thing tractable.

kick build (or the focused kick build:assets) reads assetMap from kick.config.ts. Each entry has a src path (required), an optional dest (defaults to the entry's name), and an optional glob (defaults to **/*). For every entry, the builder walks the glob, copies matching files to dist/<dest>/, and records each one in .kickjs-assets.json. After the copy, kick typegen regenerates .kickjs/types/assets.d.ts so the type system reflects what was actually emitted.

// kick.config.ts
export default defineConfig({
  assetMap: {
    mails:   { src: 'src/templates/mails',   glob: '**/*.ejs' },
    schemas: { src: 'src/schemas',           glob: '**/*.json' },
    fixtures:{ src: 'src/fixtures',          dest: 'fixtures' }
  }
});

At runtime, resolution follows a strict order. First, the manager checks KICK_ASSETS_ROOT — if set, that directory is treated as the asset root and every lookup is rooted there. Second, it tries to load .kickjs-assets.json from dist/ (or wherever the manager was initialized). Third — and only when running from source with no manifest present — it synthesizes a manifest by walking src/ according to assetMap, so that pnpm dev works without a build step.

The contract is straightforward: in production you have a manifest and the proxy is essentially a hash lookup; in dev you have a synthesized one and the proxy is essentially a filesystem walk plus a cache. Same API, same types, different machinery.

Type safety via typegen

kick typegen is the piece that closes the loop. It reads the manifest and writes a single .d.ts that augments the KickAssets interface declared by @forinda/kickjs:

declare module '@forinda/kickjs' {
  interface KickAssets {
    mails: { welcome: AssetRef; 'password-reset': AssetRef };
    schemas: { user: AssetRef };
  }
}

Once that file is on disk, assets.mails.does_not_exist() is a compile error, not a runtime exception. Filenames that are not valid identifiers — anything with a hyphen, a leading digit, a dot — are still safely addressable through bracket notation: assets.mails['password-reset'](). The generated interface uses string-literal keys for everything, so the bracket form keeps full autocomplete.

Run kick typegen (or let kick build do it for you) after any change to assetMap or to the files those entries point at. CI should treat a stale .kickjs/types/assets.d.ts as a failure.

Testing — fixture swapping

Because every lookup goes through the manifest, you can override the entire asset root at the process level by setting KICK_ASSETS_ROOT before the manager is first touched. Combined with clearAssetCache() to reset the manager between tests, this gives you a clean way to swap in fixtures without mocking.

beforeEach(() => {
  process.env.KICK_ASSETS_ROOT = path.join(__dirname, 'fixtures');
  clearAssetCache();
});

In a unit test for MailService, you can point at a fixtures/mails/welcome.ejs containing <h1>Hello {{name}}</h1> and assert on the rendered output without touching the real templates. The same trick works for snapshot fixtures, JSON-schema variants, anything where you want a known-good input.

When to reach for it

The Asset Manager is the right tool whenever the runtime answer is fs.readFile. Email templates rendered with EJS, Handlebars, or MJML. JSON schemas loaded by Ajv. Seed fixtures. PDFs and CSVs that ship with the app. Anything that lives on disk in dev, needs to live on disk in dist, and is consumed by your own server-side code.

It is not the right tool for HTTP-served static assets. Public images, downloadable user-facing files, anything a browser fetches — those want a static-file adapter or a CDN, not the Asset Manager. The line is "who reads this file?". If the answer is your handlers, use the manager. If the answer is a browser, use a serving layer.

The payoff for the in-scope cases is that you stop writing path math, you stop scattering environment checks, and you find typos at compile time instead of at 2 a.m. Once the manifest exists, the type system does the rest.

References

Dependency Injection in KickJS — Tokens, Scopes, and the Per-Request Factory

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:42:06 +0000

Dependency injection in KickJS is small on purpose. There are four surfaces, two scopes, and one pattern — a per-request factory — that does most of the interesting work. Once you know how those pieces compose, you can wire anything from a process-wide HTTP client to a request-scoped derived value through the same container, and your services keep looking like the boring constructor-and-method classes you wanted them to be in the first place.

This article walks the four DI entry points, explains when to use a token versus a class, draws the line between singleton and request scope, and then shows the one pattern that ties it together: an adapter that registers a request-scoped factory which reads request state and returns a derived handle.

The four DI surfaces

KickJS exposes DI through four distinct entry points. Each suits a different role, and a typical class will use two or three of them at once.

1. @Service() — auto-registered class. Decorate a class and the container learns to construct it. From inside any other @Service() or @Controller(), you can declare a property of that class type and the container fills it in. This is the "I wrote a class, I want it injectable" path:

@Service()
export class OrderPricingService {
  price(items: LineItem[]): Money { /* ... */ }
}

2. @Autowired(Class?) — property injection by class type. Inside a service or controller, declare a property and the container fills it before the first method runs. With no argument it uses the property's type metadata; with a class argument it disambiguates explicitly. Use this when both ends of the wire are concrete classes you own.

3. @Inject(token) — constructor or property injection by token. Use this when the type is an interface, when the implementation lives in another package, or when there are multiple implementations of the same shape and the choice is made by an adapter. Constructor form composes cleanly with classes that already have a constructor:

constructor(@Inject(MAILER) private readonly mailer: MailerService) {}

4. Container.registerInstance(token, value) / Container.registerFactory(token, fn, scope) — manual registration. This is the adapter's hook. When you have something the DI graph cannot construct on its own — a config value, a third-party client, a thing that needs async I/O at boot — you put it on the container imperatively. Use registerInstance for an already-built value that lives forever; use registerFactory when each resolve needs to compute a value (per-request derived state is the canonical case).

The first three live in service files. The fourth lives in adapters. Mix them freely: a controller that is @Service-decorated can @Autowired another service and @Inject a token in the same constructor.

Tokens vs classes

Why bother with createToken<MailerService>('MailerService') when you could @Autowired(MailerService) directly? Three reasons.

TypeScript has no nominal typing. Two interfaces with the same shape are the same interface. If you want DI to bind to "the mailer," not to "anything that happens to have send(message)," you need an explicit identity. createToken returns a frozen object that is identity-keyed — that is the whole point of it.

Cross-package interfaces. Implementations often live in adapter packages; consumers often live in domain or use-case packages. The use-case should not import the concrete class. It should import the interface (or a type-only re-export) plus the token. The token is the only runtime value crossing the boundary; everything else is a type.

Multiple implementations behind one interface. When you have a ConsoleProvider for dev and a real provider for prod, @Inject(MAILER) always resolves to whichever the adapter registered. The use-case never names a class, and swapping providers is a one-line change at the composition root.

Rule of thumb: classes for use-cases composing other use-cases inside the same app; tokens for anything that crosses an adapter boundary, has multiple implementations, or is interface-typed.

Singleton vs Scope.REQUEST

registerInstance is implicitly singleton — one value, lives until shutdown. registerFactory defaults to singleton too (the factory runs once, the result is cached), but pass Scope.REQUEST and the factory runs every request, with the result cached for the duration of that request frame.

When does each fit?

Singleton — app-level handles. A database pool, a mailer, a secrets provider, an HTTP client, a feature-flag SDK. Anything you build once, reuse forever, and tear down on shutdown. These have no per-request variance; they are shared, expensive to build, and rebuilding them between requests would be wasteful.

Scope.REQUEST — per-request derived state. Anything whose value depends on which request is in flight. A current-user object derived from the token. A request-scoped logger that prefixes log lines with the request ID. A correlation-context object. A "which one of these N pooled resources does this request want" selector. The factory runs once per request, the result is reused for that request's lifetime, and nothing leaks between requests.

The win of Scope.REQUEST over "stash it on the request object and pass it around" is that injection points stay clean. A use-case ten levels deep can @Autowired a request-scoped token and get the right value; no signature in the call chain has to thread request state through. The framework keeps a per-request DI scope alive between the request entering the kernel and the response being flushed.

Adapter-side registration

Adapters are KickJS's lifecycle primitive. They expose hooks (beforeStart, middleware, shutdown) that the kernel calls in a defined order. beforeStart({ container }) is where you populate the DI graph. The contract: beforeStart runs after every module's register() (so all @Service classes are known) but before the HTTP server listens (so the first request resolves a fully-wired graph).

The simplest adapter just registers a singleton instance:

const mailerAdapter = defineAdapter<MailerConfig>({
  name: 'MailerAdapter',
  build(config) {
    return {
      beforeStart({ container }) {
        container.registerInstance(MAILER, new MailerService(config))
      },
    }
  },
})

Three things to notice. The adapter receives its config at factory invocation time, so the composition root decides whether dev gets a console provider and prod gets a real one. The only runtime side effect is the registerInstance call. And no use-case imports the concrete class — @Inject(MAILER) is the entire contract.

The per-request factory pattern

Now the centerpiece. The pattern shows up any time you have a process-wide pool of resources and a per-request rule for picking one of them. A few examples:

A multi-tenant app with one DB client per tenant, where the active tenant is resolved from the request.
A feature-flag SDK that needs to evaluate flags against the current user, where "current user" is per-request.
A logger that prefixes structured fields drawn from request context.
A unit-of-work / transaction scope that should be the same instance for the whole request.

The shape is always the same: one process-wide registry (singleton), one factory that reads request state and returns the right slice of it (Scope.REQUEST), one token that injection sites bind to.

export const REQUEST_DB = createToken<DbHandle>('RequestDb')

// inside an adapter's beforeStart
const registry = this.dbRegistry // singleton: a Map<key, DbHandle>
container.registerFactory(
  REQUEST_DB,
  () => {
    const ctx = getRequestValue('ctx')
    if (!ctx) throw new HttpException(400, 'REQUEST_DB used outside a request scope')
    return registry.get(ctx.key)
  },
  Scope.REQUEST,
)

Three moving parts deserve attention.

The registry is a singleton. It is built once at boot and lives until shutdown. It might cache promises so concurrent first-time resolves share the same open. It typically exposes a closeAll() for the adapter's shutdown hook. The pool itself is shared; what is request-scoped is the selection.

The factory closure reads request state. getRequestValue('ctx') (or however the framework exposes per-request key/value storage) is populated upstream — by middleware, a contributor, or a guard that runs before any handler. By the time a use-case resolves the token, the value is already there, the registry hits its cache, and the factory returns the same handle every other in-flight request for the same key is using.

Failing loudly outside a request. Calling the token outside a request frame — a background worker, a CLI script, a test that forgot to set up the scope — has no request state to read. Returning undefined would push the failure into a confusing null-pointer crash deep inside a use-case. Throwing at resolve time makes the bug unmistakable: "you used this from outside a request scope." Background callers that legitimately need the resource have to either run inside an explicit request scope or call the registry directly. Either is fine; neither is a silent no-op.

The injection site stays oblivious to all of this:

@Service()
export class CreateOrderUseCase {
  @Autowired(REQUEST_DB)
  private readonly db!: DbHandle

  async execute(input: CreateOrderDTO) {
    return this.db.transaction(async (tx) => { /* ... */ })
  }
}

No resolver call, no plumbing of context through the signature, no reaching for global state. Just an injected handle that happens to be the right one for this request.

The test seam

The same surface gives you a clean test seam. In a test adapter, register an instance instead of a factory:

container.registerInstance(REQUEST_DB, fakeHandle)

registerInstance overrides whatever was registered before, so the stub wins over the real factory. Tests get a deterministic in-memory handle without spinning up infrastructure or mocking the request-state accessor. The use-case under test is none the wiser — same token, different binding, different scope (singleton in tests, request in production), and the production code does not change.

This is the payoff of token-based DI: the contract between caller and provider is one frozen object reference, and you can swap providers along any axis — environment, scope, mock vs real — without touching either side.

Putting it together

If you remember three things:

Use the right surface for the right job. @Service and @Autowired for in-app composition; @Inject(token) for cross-boundary interfaces and pluggable implementations; registerInstance / registerFactory for adapters bringing in things the graph cannot build itself.
Match scope to variance. Singleton for things that do not vary per request. Scope.REQUEST for things that do. The factory closure is your bridge between the two scopes.
Keep injection sites scope-agnostic. A use-case asking for a request-scoped token should look identical to one asking for a singleton. The token is the contract; everything else is the adapter's problem.

Once those three habits stick, DI stops being a topic you think about and becomes the boring plumbing it is supposed to be — which is exactly when it earns its keep.

References

Type-Safe Augmentation Patterns in KickJS — ContextMeta, AuthUser, PolicyRegistry

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:39:10 +0000

Decorator decorations are unsound until you augment. @Roles('owner', 'admin') looks like it is type-checked — it is not, until you tell TypeScript what AuthUser['roles'] actually is. ctx.get('tenant') looks like it returns a tenant — it does not, until you tell ContextMeta that 'tenant' is a key. @Can('delete', 'invoice') looks like a permission check — but until PolicyRegistry knows about 'invoice', both arguments are just string. KickJS v5 ships these three interfaces deliberately empty so each adopter can fill them in, and the framework's helper types pivot on whether you have. This article walks the three augmentation surfaces, the catalogue-only defineAugmentation() helper, and the file-organisation rules — generically, with minimal examples.

The general pattern

Every augmentation in KickJS uses the same TypeScript primitive — module declaration merging:

declare module '@forinda/kickjs' {
  interface ContextMeta {
    /* your keys */
  }
}

declare module '@forinda/kickjs-auth' {
  interface AuthUser {
    /* your shape */
  }
  interface PolicyRegistry {
    /* your resources */
  }
}

You are reaching into the framework's exported interface, adding members from your project, and the compiler stitches the result into a single shape at every consumption site. The framework ships each interface empty (or with a permissive index signature) so unaugmented projects continue to compile against the loose fallback; once you augment, every helper type that pivots on keyof ContextMeta or AuthUser['roles'][number] automatically tightens.

A few mechanical rules — get these wrong and the augmentation silently does nothing:

The file must be a module. Add export {} at the bottom if you do not have any other top-level imports/exports. A plain script with declare module blocks is treated as ambient and the merge does not always land where you expect.
The module specifier inside declare module '...' must match the published package name verbatim — '@forinda/kickjs' and '@forinda/kickjs-auth' are different modules, so ContextMeta lives in the first, AuthUser and PolicyRegistry in the second.
tsconfig.json must include the .d.ts file. If you put augmentations in src/types/ and your include is ["src/**/*"], you are fine. If you carved out a narrower glob, double-check.

The convention this article recommends is one file per interface, all under a dedicated src/types/ folder. The reasoning is in "Where to put augmentation files" below.

ContextMeta — typed `ctx.get()`

The framework declares ContextMeta as an empty marker interface, paired with a MetaValue<K, Fallback> helper that resolves to ContextMeta[K] if the key is registered, and to Fallback (default unknown) otherwise. ctx.get<K extends string>(key) then dispatches through MetaValue. With nothing augmented, every ctx.get('anything') resolves to unknown | undefined — strict, but it does not break the call site.

Once you augment, the same call narrows. A typical src/types/context-meta.d.ts:

import type { AuthenticatedUser } from '@/auth/types'
import type { Tenant } from '@/tenancy/types'

declare module '@forinda/kickjs' {
  interface ContextMeta {
    user: AuthenticatedUser
    tenant: Tenant
  }
}

export {}

Now ctx.get('tenant') is Tenant | undefined and ctx.get('user') is AuthenticatedUser | undefined. Two keys, two narrowings, zero runtime cost.

The contributors that populate those keys are a separate mechanism — typically defineHttpContextDecorator({ key: 'tenant', resolve: ... }) registered in your adapter layer. The relationship is worth saying out loud because beginners trip on it: the augmentation declares types, the contributor declares values. They are tied by the literal key string. If you augment ContextMeta with tenant: Tenant but never register a contributor that resolves 'tenant' for the route, the framework throws a MissingContributorError at boot when it builds the per-route pipeline. That is the system catching a typo (or a forgotten registration) before the first request hits production.

A common sub-pattern is marking certain contributors optional: true so they can no-op on routes where the value is genuinely absent (health checks, public webhooks). The | undefined already in ctx.get's return type accommodates this without callers needing extra ceremony.

AuthUser['roles'] — typed `@Roles`

@Roles is the most common decorator that benefits from augmentation, and the framework's machinery for it is the cleanest demonstration of why module merging beats subclassing or generics.

The framework's Role helper does roughly this: it looks at AuthUser['roles'], and if the type is the literal any (which it will be when AuthUser is unaugmented and falls back to its index signature), it widens Role to string; otherwise, when roles has been narrowed to a tuple or array of literal strings, it pulls the element type out and uses that. @Roles<R extends Role>(...roles: R[]) then keys off the result.

The reason that any check is load-bearing: any matches every conditional branch, so without an explicit pivot the helper would collapse to Role = any and @Roles(...) would silently accept anything — numbers, objects, undefined. The pivot keeps the unaugmented case loose-but-sane (Role = string) and lets the augmented case tighten into a proper literal union.

A minimal augmentation:

type AppRole = 'owner' | 'admin' | 'member' | 'viewer'

declare module '@forinda/kickjs-auth' {
  interface AuthUser {
    roles: AppRole[]
  }
}

export {}

After this, @Roles('owner', 'admin') typechecks and @Roles('admni') is a red squiggle at the decoration site, not a 403 in production.

There is a second layer worth noting — defense in depth. The augmentation only narrows what the TypeScript compiler can see. A forged JWT with "roles": ["god-mode"] could still arrive at runtime, and if your mapPayload returned that payload as-is, downstream @Roles checks would compare against 'god-mode' and reject the request, but the user object would carry an off-union string. The fix is to filter explicitly in mapPayload:

const allowed = ['owner', 'admin', 'member', 'viewer'] as const
const roles = (Array.isArray(payload.roles) ? payload.roles : []).filter(
  (r): r is (typeof allowed)[number] => allowed.includes(r),
)

So bogus roles are scrubbed before they ever land in the AuthUser shape. The compile-time augmentation gives you authoring safety; the mapPayload filter gives you runtime safety. The two together mean every code path that reads user.roles — @Roles, your authorization service, your service-layer ABAC checks — sees the same closed union.

PolicyRegistry — typed `@Can`

@Can('action', 'resource') follows the same pattern, with two indices instead of one. The framework declares PolicyRegistry empty, then derives PolicyResource and PolicyAction<R> from it. The trick is that when the registry has no keys at all, both helpers fall back to string so unaugmented projects keep compiling; the moment you add keys, the resource argument narrows to your declared keys and the action argument narrows per-resource:

declare module '@forinda/kickjs-auth' {
  interface PolicyRegistry {
    invoice: 'create' | 'read' | 'update' | 'delete' | 'void'
    user: 'invite' | 'suspend'
  }
}

export {}

After this:

@Can('void', 'invoice')        // ✓
@Can('delete', 'invoice')      // ✓
@Can('typo', 'invoice')        // ✗ 'typo' not in invoice's actions
@Can('invite', 'invoice')      // ✗ 'invite' is a 'user' action
@Can('delete', 'unknown')      // ✗ 'unknown' is not a registered resource

The augmentation file becomes the single source of truth: every time a new resource gains an action, you update the registry once and every existing @Can call site is re-checked.

The `defineAugmentation()` catch

There is one extra primitive that confuses everyone the first time they see it. KickJS exports a defineAugmentation('InterfaceName', { description, example }) helper, and the temptation is to assume calling it is the augmentation. It is not.

defineAugmentation is purely a discovery aid — it is a no-op at runtime and a no-op at the type level. All it does is add an entry to a typegen catalogue so the kick typegen command can render a single .kickjs/types/augmentations.d.ts file listing every augmentable interface in the project plus a worked example. A new contributor can grep that one file and see the surface area at a glance.

It does nothing to the type system. If you call only defineAugmentation and skip the declare module block, your ctx.get('tenant') is still unknown. Conversely, if you have the declare module block and skip defineAugmentation, everything works perfectly — you just lose the catalogue entry. The two are independent. Treat defineAugmentation as documentation that your linter can find.

Where to put augmentation files

A few file-organisation rules that save grief:

One block per interface, one file per block. TypeScript will happily merge multiple declare module blocks for the same interface across the project, but tools (IDE go-to-definition, code search, refactor tooling) work better when each augmentable interface has exactly one home. A typical layout: src/types/context-meta.d.ts, src/types/auth-augment.d.ts, src/types/policy-augment.d.ts. When a new resource appears, you know exactly which file to open.
Always end with export {}. Without it the file is a script, and ambient script semantics differ from module semantics in ways that bite you.
Import the value types as type-only. import type { Tenant } from '@/tenancy/types' keeps the augmentation file out of the runtime graph — .d.ts files have no runtime, but a stray value-import pulls the source file into the IDE's "go to" results and clutters refactor scope.
Confirm tsconfig.include covers `src/types/.** A .d.ts` outside the project's compilation graph does nothing, and TypeScript will not warn you.

Why this matters

The whole augmentation surface is small — three interfaces, three files — but the leverage is enormous. Every decorator, every ctx.get(key), every policy call site becomes compile-checked. When a role or resource changes in the source-of-truth file, every consumer is forced to acknowledge it. Drift between "what the auth provider hands me" and "what the decorator thinks is allowed" stops being a runtime mystery and becomes a compile error in the same PR that introduced it.

The pattern also composes. New surfaces — a typed feature-flag registry, a typed event bus, a typed job queue — fit the same shape: a framework-side empty interface, an adopter-side declare module block, a helper type pivoting on keyof or extends never, and an optional catalogue-only defineAugmentation call. That is what "type-safe by construction" looks like in v5.

References

The KickJS CLI Toolbox — Generators, Typegen, and the Configurable Build

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:37:09 +0000

Every framework ships a CLI. Most of them are scaffold-and-forget: a one-time nest new or next create, then you forget the binary exists and live inside package.json scripts forever. KickJS's kick CLI sits in a different bucket. It is the build tool, the codegen, the diagnostics surface, the package wirer, and — unusually — an interactive REPL with your DI container loaded.

This is not an enumeration of every flag. It is a tour grouped by intent, with the less-obvious commands called out.

Lifecycle — the build tool that happens to ship with the framework

The lifecycle commands are what most teams wire into package.json and forget about, but they are doing more than tsc --watch would.

kick new <name> and kick init create a new project. Pass . to init to scaffold into the current directory.
kick dev is a Vite-backed dev server with HMR. It runs typegen on startup, watches src/**/*.ts and kick.config.ts, and tears down adapters that implement shutdown() cleanly between reloads.
kick dev:debug is the same dev server with the Node.js inspector attached, so you can hook a debugger without remembering the --inspect flag pattern.
kick build runs the production Vite build and emits a single ESM bundle in dist/.
kick build:assets rebuilds only the .kickjs-assets.json manifest — useful when only static assets changed.
kick start runs the compiled production build.

These share state through generated artefacts. kick dev regenerates types as you type; kick build regenerates them before bundling; kick start assumes the build was clean. You don't think about it, which is the point.

Generators — `kick g` is the codegen surface

The bare form kick g <name> is shorthand for kick g module <name>, because that is what you reach for nine times out of ten. The full set of subcommands covers the whole granularity ladder.

Full-feature generators:

module — a complete module folder: controller, service, DTOs, repo, tests, and (critically) registration in src/modules/index.ts.
scaffold — full CRUD module driven by a field DSL (more on this in a moment).
auth-scaffold — a complete auth module: register, login, logout, password hashing, controller, service, DTOs, test stubs.
plugin — a KickPlugin that bundles DI bindings, modules, adapters, and middleware behind a single registration.
adapter — an AppAdapter with lifecycle hooks (start, shutdown).

Single-file scaffolds:

service, controller, dto, test — each takes -m <module> to scope it to an existing module folder.
middleware — Express middleware (also -m-scopable).
guard — a route guard (auth, roles, anything per-route).
job — a @Job queue processor with @Process handlers, for kick add queue consumers.
resolver — a GraphQL resolver scaffold with the right decorators wired up. Opt-in: only relevant if you're running a GraphQL surface alongside (or instead of) HTTP routes.

Project-level generators:

config — emit a fresh kick.config.ts.
agents and agent-docs — regenerate AGENTS.md, CLAUDE.md, and kickjs-skills.md from the framework's current state.

Cross-cutting flags worth knowing: --list shows what a generator can do without writing anything, --dry-run prints the file plan, --repo (inmemory | drizzle | prisma) picks the persistence flavour, --pattern (rest | ddd | cqrs | minimal) picks the architectural dialect, --minimal / --no-entity / --no-tests / --no-pluralize strip pieces you don't want, and -f / --force overwrites existing files.

kick g module orders --repo drizzle --pattern rest

That registers OrdersModule in src/modules/index.ts for you. The registration step is the one you must not hand-roll: it is alphabetised, import-managed, and aware of removal via kick rm. Hand-edit it and you will eventually leave a dangling import behind.

The unusual ones, paragraph by paragraph

These are the commands that most other frameworks don't have, or only have in some half-built form. They're the reason the CLI is interesting and not just convenient.

`kick g scaffold` and the field DSL

kick g scaffold takes a list of field specs and emits a full CRUD: Zod input DTO, response DTO, controller (list/get/create/update/archive), use-case files, and tests. The DSL is the trick:

kick g scaffold Post title:string body:text:optional published:boolean:optional

Supported types: string, text, number, int, float, boolean, date, email, url, uuid, json and enum:a,b,c for inline enums. Append :optional and the Zod schema marks it nullable, the TypeScript type widens, and the test fixtures stop passing it. The right tool when you know the shape of an entity and don't want to type it four times across DTO, response, repo, and test.

`kick g auth-scaffold`

kick g auth-scaffold is g scaffold for the one feature every app re-implements badly: authentication. It emits a controller (/auth/register, /auth/login, /auth/logout), a service with password hashing, the DTOs you actually want, and test stubs. The point isn't that it saves typing; it's that the resulting code is the same shape across every KickJS app, so onboarding onto a new project, you already know where the login handler lives.

`kick tinker`

kick tinker boots an interactive REPL with the DI container and your services pre-loaded — the Laravel/Rails ergonomic, ported into Node. Drop into a prompt, type await container.resolve(OrdersService).list({ limit: 5 }), and you have data back without writing a script, mocking a request, or curl-ing a route. For exploratory work — "what does this query return for tenant X?" — it beats a debugger.

`kick explain`

kick explain "<error message>" takes a KickJS error string and returns a description plus a likely fix from the framework's own catalogue. You're not searching GitHub issues; you're asking the binary that produced the error what it meant. A small thing that's disproportionately useful the first month on a new framework.

`kick mcp`

kick mcp start and kick mcp init expose the framework over the Model Context Protocol — the spec that lets AI assistants treat tools as first-class resources. With kick mcp running, an assistant can introspect your modules, ask the framework for the DI registry, or trigger generators safely. The first framework I've seen ship its own MCP server in the box — a clear opinion that AI tooling is part of the developer surface, not a third-party add-on.

`kick g agents`

The companion to kick mcp is kick g agents, which regenerates AGENTS.md, CLAUDE.md, and kickjs-skills.md from the framework's current capabilities. The interesting bit is what it implies: the framework treats keeping the AI-tooling docs fresh as part of its own upgrade process. Bump the framework, re-run kick g agents, and your AI tooling is back in sync. The doc isn't a side artefact; it's a build output.

Packages — `kick add` is not a synonym for `pnpm install`

kick add auth does what pnpm install @forinda/kickjs-auth does, and wires it. It registers the package's adapters with the bootstrapper, drops imports into src/index.ts where needed, and scaffolds the config block (JWT secret slot, refresh strategy slot) so you have somewhere to put secrets without reading the package README first. The package ships a manifest, the CLI applies the wiring, and prints what it changed.

kick list (alias kick ls) prints every package the CLI knows how to wire — the answer to "is there an official kickjs package for cron?" without leaving the terminal.
kick remove (alias kick rm) removes generated code with awareness of the registry files. kick rm module orders undoes what kick g module orders did, including the modules/index.ts line.

Diagnostics & DX — the bits other CLIs ship as third-party tools

None of these are scripts wrapping npm run.

kick info prints system + framework info: Node version, TS version, KickJS version, package versions, OS. The first thing you paste into a bug report.
kick check audits the project for common issues — missing types, drift between kick.config.ts and the generated registry, packages added via pnpm without the kick add wiring step.
kick inspect [url] connects to a running KickJS app and pulls live debug info: registered routes, DI bindings, adapter status.

Cumulatively, you can answer "what's wrong with my app?" without leaving the CLI — novel only if you remember how many frameworks make you write a script, run a curl, or boot an inspector to ask the same questions.

Quality — the CI gate

The quality commands are small in scope but hold the project together over time.

kick typegen regenerates .kickjs/types/: route types (so ctx.body matches your Zod schema), env types (so getEnv('PORT') is typed), DI registry tokens, module + plugin declarations, asset imports, ContextMeta augmentations. gitignored, treated as a build artefact. kick dev runs it on change; CI runs it before typecheck and build. You rarely run it by hand.
kick test is a passthrough to Vitest with the project's config preloaded.
kick format runs Prettier; kick format:check checks without writing.
kick ci:check (alias kick verify) is the CI gate: typecheck + format check, in the order that fails fastest.

A minimal synthetic kick.config.ts ties it together:

import { defineConfig } from '@forinda/kickjs-cli'

export default defineConfig({
  pattern: 'rest',
  modules: { dir: 'src/modules', repo: 'drizzle', pluralize: true },
  typegen: { schemaValidator: 'zod' },
  commands: [
    { name: 'lint', description: 'Lint code', steps: 'eslint src/' },
  ],
})

pattern picks the controller dialect. modules.dir / modules.repo / modules.pluralize set generator defaults. typegen.schemaValidator: 'zod' tells typegen to crack open Zod schemas for body inference. commands lets you register custom verbs that run as kick lint, with the same logging the built-ins get.

What makes this CLI different

KickJS folds five things — build tool, codegen, package manager wrapper, diagnostics, REPL — into one binary, and ships an MCP server so AI assistants can introspect the app. Most Node frameworks ship one or two of those and rely on you to assemble the rest from package.json scripts and third-party tools. The design decision is worth stealing: a single CLI that stays useful from kick new through to kick tinker on a five-year-old codebase is the one you'll still trust on day 1500.

References

BYO in KickJS v5 — Building Your Own Mailer (and Why That's a Good Thing)

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:35:07 +0000

If you went looking for @forinda/kickjs-mailer on npm and found a deprecation banner instead of a v5 release, here's the punchline: the package isn't gone. It's just... yours. The framework still has everything you need to wire a mailer into the DI container — defineAdapter, createToken, lifecycle hooks — and the email surface turns out to be small enough that owning it in your own repo is the better trade. This post walks through what that pattern looks like, why it matters, and how to lay out the four pieces every BYO mailer collapses to.

What got deprecated and why

The README on the abandoned package is unusually direct. Quoting verbatim:

Deprecated — going private in v4.1.2. Replaced by a BYO recipe using defineAdapter/definePlugin from @forinda/kickjs directly.

That sentence captures a philosophical shift in how the framework treats peripheral concerns. KickJS v5 still publishes opinionated packages for the things you don't want to reinvent — auth strategies, queue drivers, OpenTelemetry wiring, ORM adapters. But for surfaces that are essentially "an interface, a service, and a default implementation," shipping a package starts to cost more than it saves. You inherit a versioning pact ("does mailer 2.x work with kickjs 5.x?"), a peer-dep graph, and a public API that has to evolve in lockstep with three transports nobody on the maintainer's machine actually uses.

The recipe approach inverts that. The framework guarantees the primitives — defineAdapter, the DI container, the request lifecycle. Recipes documenting how to assemble those primitives into common shapes live in the docs. Your project owns the assembled artifact. When the primitive's signature is stable across the major, your recipe-based mailer is stable across the major. No transitive churn.

Recipe, not package

A package ships a finished thing — code, types, a published version, a public API contract. A recipe ships a shape: "here's how to compose four primitives into a mailer; copy it, adjust it, own it." The framework promises that the primitives are stable. The recipe lives in your repo and serves only your app, so it's sized to your app — only the providers you actually use, only the options you actually configure. Fewer lines of code under your control instead of more lines of code under someone else's release schedule.

The four pieces

Every BYO mailer collapses to the same four pieces. They don't change much between projects, which is exactly why the framework stopped trying to ship them as a unit:

Types — MailMessage, MailResult, MailRecipient. The shape of what callers send and what they get back. Plain interfaces, no decorators, no DI.
Provider interface — MailProvider with one method: send(message): Promise<MailResult>. This is the seam tests stub, the seam ops swaps per environment, and the only contract a transport implementation has to satisfy.
Service — MailerService. The class injected into use-cases. It wraps a provider and adds the small amount of cross-cutting logic every call site would otherwise repeat — typically a default from address, sometimes a logger, sometimes a tag.
Adapter factory — the defineAdapter call. Produces a typed factory that registers the service against an injection token in the DI container during beforeStart. Composition lives at the edge: pass it whichever provider this environment needs.

Each piece is one screen of code. None depends on the framework beyond defineAdapter and createToken. That's the recipe.

What the types look like

The types are deliberately boring — interfaces, not classes, no inheritance:

export interface MailMessage {
  readonly from?: MailRecipient
  readonly to: MailRecipient | MailRecipient[]
  readonly subject: string
  readonly text?: string
  readonly html?: string
}

export interface MailResult {
  readonly messageId: string
  readonly accepted: boolean
}

export interface MailProvider {
  readonly name: string
  send(message: MailMessage): Promise<MailResult>
}

export const MAILER = createToken<MailerService>('MailerService')

A useful trick when migrating off a deprecated package: mirror the old shape on purpose. If your callers already say mailer.send({ to, subject, html }), keep that exact signature. BYO doesn't have to mean "redesign your email API" — it usually means "lift the same shape, drop the dep." The injection token plays the same role: it's the contract between callers and the adapter, so use-cases reference MAILER and never know which provider is actually wired underneath.

The service stays small on purpose

The service itself is small, and that's a feature:

export class MailerService {
  constructor(private readonly opts: { provider: MailProvider; defaultFrom: MailRecipient }) {}

  async send(message: MailMessage): Promise<MailResult> {
    return this.opts.provider.send({
      ...message,
      from: message.from ?? this.opts.defaultFrom,
    })
  }
}

Notice what's not in there: no template engine, no retry policy, no rate limiting, no queue handoff. Those are real concerns for some apps — they're just not concerns for the mailer service itself. Templating belongs in a render layer above; retries belong in a queue layer below. Keeping the service to "stamp from, delegate" means it's still recognisably the same class six months from now when those layers do show up.

If you find yourself reaching for an additional concern, ask whether it belongs inside send or around it. "Inside" is almost always the wrong answer. A 300-line mailer with hand-rolled exponential backoff is a code smell; pushing the message onto a queue and letting the queue owner handle retries is the shape that scales.

A console provider for dev

The most useful default provider in early development is one that logs to the console:

export class ConsoleMailProvider implements MailProvider {
  readonly name = 'console'
  private counter = 0

  async send(message: MailMessage): Promise<MailResult> {
    this.counter += 1
    const id = `console-${this.counter}`
    console.info(`mail[${id}] -> ${message.to} :: ${message.subject}`)
    return { messageId: id, accepted: true }
  }
}

Zero dependencies. Zero network calls. You can run the whole bootstrap, exercise password-reset, signup confirmation, anything that emits mail, and watch it scroll past in your dev terminal. When you're ready to send for real, you swap one constructor.

The adapter factory

The piece that ties it to the DI container:

const mailerAdapterFactory = defineAdapter<MailerAdapterConfig>({
  name: 'MailerAdapter',
  build(config) {
    return {
      beforeStart({ container }) {
        container.registerInstance(
          MAILER,
          new MailerService({ provider: config.provider, defaultFrom: config.defaultFrom }),
        )
      },
    }
  },
})

export function createMailerAdapter() {
  return mailerAdapterFactory({
    provider: new ConsoleMailProvider(),
    defaultFrom: { name: 'App', address: 'noreply@example.com' },
  })
}

export { mailerAdapterFactory }

Two exports, two purposes. createMailerAdapter() is the production ergonomics — call it from your bootstrap, get the dev-defaulted mailer registered. mailerAdapterFactory is the raw factory exposed for tests and per-environment composition: pass any MailProvider, get an adapter that registers a service wrapping it. That's the entire surface.

The test seam

Because MailProvider is a one-method interface, the test double is genuinely trivial:

export class CapturingMailProvider implements MailProvider {
  name = 'capturing-test'
  sent: MailMessage[] = []

  async send(message: MailMessage): Promise<MailResult> {
    this.sent.push(message)
    return { messageId: `test-${this.sent.length}`, accepted: true }
  }

  reset() { this.sent.length = 0 }
}

Each integration test instantiates a CapturingMailProvider, threads it into the test container's mailer registration via the raw factory, and asserts on subject / html / to after exercising the endpoint. If a flow embeds an OTP or a magic link in the email body, the test scrapes it back out of the captured payload — a thin helper on the test provider keeps that readable.

Compare what stubbing the old package would have looked like: mock the export, stub send, hope the mock signature matches whatever version of the package you happened to pull. Owning the interface means the stub is just a class.

Dev to prod is one constructor swap

This is where the recipe actually saves money. Today, dev runs on ConsoleMailProvider. When transactional mail lands, swapping to a real transport is one constructor swap inside createMailerAdapter():

// before
provider: new ConsoleMailProvider(),

// after
provider: new ResendMailProvider({ apiKey: env.RESEND_KEY }),
// or
provider: new SmtpMailProvider({ host, port, user, pass }),

The service doesn't change. The injection token doesn't change. Every mailer.send({...}) call site doesn't change. There's no peer-dep version chase, no "does the new mailer package work with kickjs 5.7?", no transitive nodemailer upgrade landing in your lockfile because the package author bumped a dep. You wrote ~30 lines of ResendMailProvider, you own those 30 lines, and that's the whole change.

The same composition pattern means staging on SMTP, prod on a transactional API, e2e on the capturing provider — same adapter factory, three different provider: values. No package matrix to maintain.

When you should still ship a package

Recipes win for surfaces that are basically "an interface plus a default." They lose when the default implementation has significant shared logic (token rotation, signature verification, multi-region routing) every caller would otherwise duplicate, when the contract has to evolve in coordination with an external spec, or when the thing genuinely benefits from being battle-tested across many consumers. Mailers fail all three. Once you notice the pattern, you start spotting it elsewhere: feature flags, audit logs, idempotency keys. Recipe-shaped surfaces all the way down.

Why this is better

Three concrete wins from doing it this way:

Smaller dep tree. No mailer package means no nodemailer (or whatever the package would have pulled in) until you actually want it. A console provider has zero deps. CI installs are faster, supply-chain surface is smaller, and you don't get CVE pings for transports you aren't using.
No upstream churn. When kickjs ships v5.8, your mailer doesn't need a coordinated release. defineAdapter is the API contract, and that's part of the framework core. As long as the core's stable, your recipe is stable.
Trivial per-environment swaps. Same adapter factory, different provider: values per env. No package matrix, no dual-publishing dance, no "is the test provider on the same major as prod?"

That's the trade KickJS v5 is pushing you toward across the small-surface concerns: own the recipe, lean on the primitives. The mailer is just the most readable example because everyone has written one.

References

Adapters vs Plugins in KickJS v5 — Choosing the Right Primitive

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:32:50 +0000

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.

References

The KickJS Request Lifecycle — Middleware, Contributors, and Typed Context

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:31:35 +0000

There is a tempting first read of KickJS where ctx looks like a friendlier wrapper around Express's req/res. It is not. Treating ctx as "req in disguise" is the single fastest way to write code that fights the framework — you reach for req.user, you read headers off req.headers, you sprinkle requireX(ctx) helpers around handlers, and the type system never quite catches up. Once you understand that ctx is a typed, contributor-populated object that lives on top of a per-request store — and that the lifecycle is staged across phases the framework actually controls — the whole stack starts pulling in the same direction. This article walks the KickJS request lifecycle end to end as a conceptual model you can apply to any KickJS app.

The phases, in firing order

A request to a KickJS app is not a flat chain. It moves through three distinct stages, in this order:

HTTP request
    │
    ▼
┌─────────────────────── Adapter middleware ───────────────────────┐
│  beforeGlobal   →  before kickjs's framework middleware          │
│  afterGlobal    →  after framework middleware, BEFORE routes     │
│  beforeRoutes   →  per-router, before the matched handler        │
│  afterRoutes    →  per-router, after the handler resolves        │
└──────────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────── Per-route contributors ───────────────────┐
│  Pipeline built from `bootstrap({ contributors: [...] })`        │
│  Each contributor's `resolve(ctx)` runs once, result cached      │
│  in the per-request store under its `key`                        │
└──────────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────── Controller handler ───────────────────────┐
│  async handler(ctx: Ctx<KickRoutes.Foo['op']>) {                 │
│    const session = ctx.get('session')   // typed, never unknown  │
│  }                                                               │
└──────────────────────────────────────────────────────────────────┘

Adapter middleware is where infrastructure lives — body parsing, auth strategies, request shaping. Contributors are where derived, per-request values get computed, typed, and cached. The handler is where business logic actually runs. The line between these stages is rigid on purpose: middleware mutates req, contributors read ctx, handlers consume both via ctx.get() and the typed Ctx<T> shape from KickRoutes.

The four middleware phases — beforeGlobal, afterGlobal, beforeRoutes, afterRoutes — are not aesthetic. They give you a deterministic place to plug in things like "I need to run before kickjs registers its own framework middleware" (beforeGlobal) versus "I need every request to have a session attached, but I do not want to be inside any specific router yet" (afterGlobal).

Adapter middleware

A typical adapter mounts handlers at the phases it cares about:

middleware(): AdapterMiddleware[] {
  return [
    {
      phase: 'afterGlobal',
      handler: (req, _res, next) => {
        req.session = lookupSession(req.headers.authorization)
        next()
      },
    },
  ]
}

Two things matter here. First: the middleware does not touch ctx. It mutates the underlying Express Request only. Second: it is registered as phase: 'afterGlobal' precisely because it must run after KickJS's framework middleware (so that body parsing, request id, etc. are in place) but before any router or contributor sees the request. If you put it at beforeRoutes you would have to mount it on every router. If you put it at beforeGlobal you would race the framework's own initialization. afterGlobal is the right joint for cross-cutting infrastructure that every route depends on.

Use beforeRoutes/afterRoutes for per-router concerns (a logging shim around one feature module, a guard that only one router exposes). Use beforeGlobal sparingly — it sits in front of the framework's own request id, error handling, and body parsing, so most of the time it is not what you want.

The pattern to internalize is: adapter middleware stamps things onto req. Contributors lift those things into the typed ctx.

Contributors: typed `ctx.get()`

A contributor is just an object built by defineHttpContextDecorator. The minimal shape:

export const LoadSession = defineHttpContextDecorator({
  key: 'session',
  resolve: (ctx) => {
    const session = ctx.req.session
    if (!session) {
      throw new HttpException(HttpStatus.UNAUTHORIZED, 'no session')
    }
    return session
  },
})

Four properties matter:

key — the string that handlers will use in ctx.get('session'). It is also the property in the ContextMeta interface that gives the read its type.
resolve(ctx) — the function that produces the value. Runs once per request, lazily, the first time something asks for it. The return value is cached in the per-request store under key.
optional — when true, a throw inside resolve is swallowed silently and the key is simply not set; ctx.get('key') returns undefined. When false (the default), a throw aborts the request with whatever HttpException you raised. Use optional: true for values that legitimately may not exist (anonymous endpoints, public webhooks) so the request does not 500 just because the contributor cannot build its value.
dependsOn — an array of other contributor keys that must resolve first. KickJS's buildPipeline topologically sorts contributors using these dependencies. If LoadProfile declared dependsOn: ['session'], the pipeline would guarantee LoadSession ran first. If a contributor declared a dependency on a key that no contributor exposes, buildPipeline would reject the registration at boot — the framework refuses to silently ignore a missing dependency.

Once you call bootstrap({ contributors: [LoadSession.registration, ...] }), those contributors run on every route automatically. Handlers consume the result with ctx.get('session') — typed — instead of reading ctx.req.session and reinventing the null check at every callsite.

The contract is simple: if you read a value via ctx.get, the framework either gave you that value or threw an HttpException with a message you can grep for. There is no "sometimes typed, sometimes undefined" middle ground muddying handler code.

Augmenting `ContextMeta`

ctx.get('session') is typed, but only because the app told the framework what session actually is. The augmentation lives in a .d.ts file your app owns:

import type { Session, Profile } from './types'

declare module '@forinda/kickjs' {
  interface ContextMeta {
    session: Session
    profile: Profile
  }
}

export {}

That declare module block is the one TypeScript trick that makes the entire ctx.get() story worth using. KickJS's ContextMeta interface is defined empty in the framework. When your app augments it, every call to ctx.get<K extends keyof ContextMeta>(k: K): ContextMeta[K] | undefined (or the non-undefined overload when the contributor is non-optional) returns the narrowed type instead of unknown.

The trailing export {} is required to keep the file a module rather than a script — without it, declare module does not augment correctly. If you skip the declare module block entirely, every ctx.get() returns unknown and your handlers fight the type system instead of leaning on it. This file is small but every line is load-bearing.

A useful discipline: keep one context-meta.d.ts per app. Domain packages that ship contributors should export the type they augment, and the app composing them does the actual declare module once. That keeps augmentation centralized and easy to audit.

The `dependsOn` trap

Here is the canonical bug. Suppose a contributor needs the user that an auth strategy populates onto req.user, and you write:

export const LoadProfile = defineHttpContextDecorator({
  key: 'profile',
  dependsOn: ['user'], // looks reasonable. it isn't.
  resolve: (ctx) => buildProfile(ctx.req.user),
})

The intent is correct: the profile needs the user. The problem is that user is not a contributor. req.user is populated by the auth strategy's adapter middleware, which runs in the afterGlobal/beforeRoutes phase before any contributor pipeline executes. There is no LoadUser.registration in the bootstrap({ contributors }) array — there cannot be, because the auth adapter owns that responsibility.

buildPipeline checks every dependsOn key against the registered contributor set. When it sees dependsOn: ['user'] and finds no contributor with key: 'user', it raises a MissingContributorError at boot. The fix is to drop the false dependency and trust the lifecycle:

export const LoadProfile = defineHttpContextDecorator({
  key: 'profile',
  // no dependsOn — auth middleware ran in afterGlobal,
  // so ctx.req.user is already populated by the time resolve runs
  resolve: (ctx) => buildProfile(ctx.req.user),
})

The mental model to keep is: dependsOn is for ordering between contributors, not for declaring "I need something on ctx." If the value comes from middleware, you read it inside resolve and rely on phase ordering. If the value comes from another contributor, you declare the edge and let the framework topo-sort. Mixing the two produces boot-time errors that look mysterious until you remember which layer owns which keys.

Why contributors > helpers

Before contributors, the natural pattern is a requireX(ctx) helper imported into every handler that needs X:

const session = requireSession(ctx) // throws 401 if missing

That helper is fine in isolation. It is also duplicated logic, untyped at the framework level (the helper returns the right type only because the helper itself is typed — the framework does not know about it), and impossible to compose with auth or audit concerns without a second helper, then a third. The pattern makes the framework lifecycle invisible: the throw happens wherever the helper got called, so the same "no session" error surfaces in twelve different stack frames.

ctx.get('session') collapses all of that:

The error message lives in one place — inside LoadSession.resolve. Change it once, the whole app updates.
The retrieval is typed via ContextMeta augmentation. No helper indirection.
The framework decides when resolve runs, caches the value, and integrates with optional for routes that legitimately do not need it.
Adding a new derived value is a registration, not a new helper file with its own import surface.

A handler now just looks like this:

async create(ctx: Ctx<KickRoutes.WidgetsController['create']>): Promise<void> {
  const widget = await this.createWidget.execute(ctx.body, ctx.get('profile')!)
  ctx.created(toWidgetDTO(widget))
}

ctx.body is typed from the route's Zod schema. ctx.get('profile') is typed from ContextMeta. The ! is the explicit acknowledgement that this route is authenticated, so the optional contributor will have resolved. There is no helper, no requireSession, no per-handler null check. The framework handled it.

Putting it together

Read the request as a pipeline:

Express receives the request. KickJS's framework middleware runs (beforeGlobal adapter middleware first, then framework internals).
afterGlobal middleware fires. Auth strategies, session resolvers, and other cross-cutting infrastructure stamp values onto req.
The route is matched. beforeRoutes middleware runs (per-router auth guards, role checks, etc.).
The contributor pipeline executes. Each registered contributor's resolve runs once, in topological order based on dependsOn. Results are cached in the per-request store.
The handler runs. ctx.get(key) returns typed values; ctx.body/ctx.params/ctx.query are typed from KickRoutes.
afterRoutes middleware fires for cleanup (logging, response shaping). The response goes back.

Each layer has one job. Middleware mutates the request. Contributors compute and cache derived values. Handlers consume typed ctx. The framework polices the boundaries — dependsOn enforces contributor ordering, ContextMeta enforces typed reads, MissingContributorError blocks boot when the wiring is wrong.

Once you internalize this, the helper-per-concept style starts to feel like writing your own framework on the side. Contributors are not magic; they are just a place for derived per-request state to live with type safety, lifecycle integration, and a single throw site. That is what makes ctx worth more than req.

References

Authentication and Authorization in KickJS — Strategies, Roles, and Type-Safe Decorators

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:29:48 +0000

For most of last year, the cheapest way to ship a security regression in a TypeScript API was a single typo:

@Roles('owener', 'admin')   // shipped. nobody noticed. forever-403.

@Roles accepted any string. Tests still passed because they used the spelled-correctly literal. The route silently rejected every request. KickJS v5 fixes this: @Roles is now narrowed by your project's own role union via a one-file declare module augmentation, so misspellings become a compile error before they leave the editor. This post walks the full auth surface in KickJS — AuthAdapter, the AuthStrategy interface, @Authenticated, @Roles, @Public — at a conceptual level, with small generic snippets you can map onto any KickJS app.

The shape of auth in KickJS

KickJS keeps auth deliberately small. There are three concepts to learn, and they compose cleanly.

AuthAdapter — an AppAdapter (the same plug used for observability, swagger, db) constructed via createAuthAdapter(). You hand it a defaultPolicy ('protected' or 'public') and an array of strategies. It registers a per-request middleware that runs strategies in order, attaches the resolved user to req.user, and returns 401 on failure.
AuthStrategy — an interface: name: string plus validate(req): Promise<AuthUser | null>. Built-ins live in @forinda/kickjs-auth (JwtStrategy, ApiKeyStrategy); custom strategies are just classes implementing the interface.
Decorators — @Authenticated('strategy-name') opts a controller or route into a specific strategy; @Roles(...) narrows the user's role; @Public() marks a route as anonymous. They compose at any level — controller-class, method, or both.

The big idea: strategy choice and role check are separate axes. @Authenticated says who is allowed to identify you; @Roles says what they need to be. Some routes only need the first (a synthetic system user has no roles); some need both (regular CRUD needs JWT plus an authorized role).

Wiring AuthAdapter

A typical adapter file looks like this:

export function createAuthAdapter(): AppAdapter {
  return AuthAdapter({
    defaultPolicy: 'protected',
    strategies: [
      JwtStrategy({ /* ...covered next... */ }),
      new ServiceTokenStrategy(),
    ],
  })
}

Two production-grade habits to copy:

defaultPolicy: 'protected'. Every route requires a valid user unless explicitly @Public(). The opposite default ('public') is the path to forgetting @Authenticated on a sensitive endpoint and shipping it. Default-deny costs you @Public() on three routes (health, login, refresh) and protects everything else automatically.
Refuse to construct against an unresolved secret. If your env layer keeps secrets symbolic in committed config and a resolver swaps them at boot, the adapter must throw when it finds a placeholder value — otherwise it would silently sign or verify with the literal placeholder string. Steal the pattern: any factory that consumes a secret should refuse to build against an unresolved sentinel.

The adapter is a factory, not a class. KickJS auth v4 dropped construct signatures on AuthAdapter and JwtStrategy; calling them with new raises TS7009. If you're migrating from v3, that's the diff to make.

JWT with claim mapping

JwtStrategy does the heavy lifting — Bearer parsing, signature verify, expiry. The interesting bit is mapPayload, which turns a verified JWT payload into your app's user shape:

JwtStrategy({
  secret: env.JWT_SECRET,
  algorithms: ['HS256'],
  mapPayload: (payload): AppAuthUser => {
    if (payload.iss !== env.JWT_ISSUER) throw new Error('iss mismatch')
    const claimed = Array.isArray(payload.roles) ? payload.roles : []
    const roles = claimed.filter((r): r is AppRole => KNOWN_ROLES.has(r))
    return { id: String(payload.sub ?? ''), roles }
  },
})

Three things worth flagging:

Issuer/audience enforcement inside mapPayload. Some JwtStrategy versions don't forward issuer/audience to the underlying verifier. The workaround is small: do the comparison yourself and throw on mismatch. Throwing inside mapPayload bubbles up as a strategy failure — the adapter returns 401, the handler never runs. If a future version adds first-class options, the migration is deleting a few lines.

Role filtering as defense in depth. Filter the JWT's roles claim through your known role union — drop anything else silently. Real validation belongs at issue time (the login path checks against your membership store), but defense in depth is cheap here and stops a class of bugs where downstream code accidentally trusts an unknown role string.

Returning a typed user. The return type extends AuthUser with whatever your app needs (id, email, a typed roles array, maybe a jti for revocation). Because of the augmentation we'll see next, downstream @Roles(...) calls share that exact union.

A second strategy for a second audience

Sooner or later you have routes that aren't part of your normal user-token flow — service-to-service callers, a control plane, a CI bot, an internal admin endpoint. Stuffing them into the same JWT issuer means either issuing privileged tokens out of the user login path or carrying a flag in user tokens that breaks isolation. Don't do either. Add a second strategy.

A minimal shared-token strategy looks like this:

export class ServiceTokenStrategy implements AuthStrategy {
  readonly name = 'service-token'
  async validate(req: Request): Promise<AppAuthUser | null> {
    const expected = (process.env.SERVICE_TOKEN ?? '').trim()
    if (!expected) return null
    const header = req.headers?.authorization ?? ''
    if (!header.toLowerCase().startsWith('bearer ')) return null
    const provided = Buffer.from(header.slice(7).trim())
    const want = Buffer.from(expected)
    if (provided.length !== want.length) return null
    return timingSafeEqual(provided, want)
      ? { id: 'service', roles: [] }
      : null
  }
}

A few notes worth internalizing:

timingSafeEqual. Constant-time comparison stops the trivial timing attack on simple-token auth. If you're going to ship a shared bearer at all, do this.
Read process.env directly when you want HMR and test-stubs to "just work". Cached env snapshots are great for app config but get in the way for strategies that need to reflect runtime changes during tests.
Synthetic users are fine. A service caller doesn't need a row in your users table. A constant { id: 'service', roles: [] } is enough — the strategy is the gate.

Now look at registration order:

strategies: [
  JwtStrategy({ /* ... */ }),
  new ServiceTokenStrategy(),
],

Order matters. KickJS picks "the first strategy that returns a user." JWT runs first, so user routes resolve their JWT-derived user. The service strategy only matches when a route opts in via @Authenticated('service-token'):

@Controller()
@Authenticated('service-token')
export class InternalOpsController { /* ... */ }

The combination of (default-deny + ordered strategies + opt-in @Authenticated('strategy-name')) is what keeps the two audiences cleanly separated.

Type-safe @Roles via AuthUser augmentation

Here's the piece that earns its keep. @Roles(...) in KickJS v5 is generic over AuthUser['roles'][number]. Inside @forinda/kickjs-auth the relevant type is roughly:

type Role = AuthUser['roles'][number]
function Roles(...roles: Role[]): MethodDecorator & ClassDecorator

By default AuthUser['roles'] is string[], so Role resolves to string — which is why old @Roles('typo') compiled. The fix is a one-file declaration merge in your app:

// src/types/auth-augment.d.ts
import type { AppRole } from '@/auth/roles'

declare module '@forinda/kickjs-auth' {
  interface AuthUser {
    roles: AppRole[]
  }
}

export {}

Define your role union in exactly one place:

// src/auth/roles.ts
export type AppRole = 'owner' | 'admin' | 'editor' | 'viewer'

After the augmentation, AuthUser['roles'] is AppRole[] everywhere — including inside the framework, including inside the Roles decorator's generic. The package uses an IsAny-pivoted conditional to pick this up cleanly: if user code augments AuthUser, Role resolves to your union; if not, it falls back to string so unconfigured projects still compile.

Concretely:

@Controller()
@Authenticated('jwt')
export class PostsController {
  @Post('/')
  @Roles('owner', 'admin')
  async create() { /* ... */ }
}

@Roles('owner', 'admin') typechecks. @Roles('owener', 'admin') doesn't — TS reports Argument of type '"owener"' is not assignable to parameter of type 'AppRole'.

That's the proof. The same typo that used to ship is now a red squiggle in the IDE and a CI failure on pnpm typecheck. The cost was a six-line .d.ts file. The payoff: adding a new role is one line in roles.ts, and TypeScript tells you every controller that already references it correctly — and refuses to compile any that misspell it.

Two small bits of polish that make this nicer to live with:

Make the augmentation visible to tsc. Drop a side-effect import in src/index.ts (or in a barrel re-exported by it) so the file is part of the compilation unit. tsc won't apply a declare module it never sees.
Keep the union in one file. Import the role type everywhere from the same module — including inside the mapPayload filter. When the union grows, adding a literal updates the filter, the augmentation, and every @Roles call site in lockstep.

Where @Roles doesn't belong

The service-token controller above used @Authenticated('service-token') and no @Roles(...). That's deliberate. The synthetic service user has roles: []. If you slapped @Roles('admin') on a method, the check would fail — the synthetic user has none of your normal roles, by design.

Privileged-channel gating is the strategy choice itself: passing the strategy is the authorization. Your normal role union stays scoped to user-facing routes, which keeps two concerns from leaking into each other. If you later need richer role semantics on the privileged channel, give it its own union and its own decorator (@ServiceRoles(...)) kept disjoint from the user role type on purpose.

The takeaway for your own designs: not every protected route needs @Roles. If the strategy can only ever produce one kind of user, the strategy is the gate.

Putting it together

The mental model fits on one index card:

Pick a default policy. Default-deny unless you have a very good reason.
List your audiences. Each audience is one strategy with one name.
Order them by which one should win when more than one could match.
On controllers, pick the audience with @Authenticated('name'). On @Public() routes, opt out explicitly.
On routes, pick the role with @Roles(...) — but only when the strategy actually issues users with roles.
Augment AuthUser['roles'] once with your real role union. Now misspellings are a build error.

Auth surfaces are usually where frameworks accumulate accidental complexity, and most of the bugs that result are cheap to ship and expensive to find. KickJS keeps the surface narrow, makes the safe defaults the easy ones, and pushes role correctness from runtime into the compiler. After you've lived with the augmentation for a sprint, dropping back to "any string is a valid role" feels reckless.

References

Inside KickJS Adapters — Lifecycle, Composition, and Custom Patterns

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:28:01 +0000

If you have written an Express app, you already know the shape of a middleware: a function that gets (req, res, next) and runs once per request. You probably also know what a plugin looks like — a side-effecting register(app) call that mutates a global at boot. KickJS gives you a third primitive sitting between those two, and most of the framework's interesting behaviour lives there: the adapter. An adapter is not per-request like middleware, and it is not a one-shot side-effect like a plugin. It is a typed object with a lifecycle, composed in order, orchestrated by the framework so your app can stand long-lived infrastructure up and tear it down deterministically.

What an adapter is

An adapter is a unit of composable infrastructure plugged into the KickJS bootstrap pipeline. You reach for one whenever a concern needs more than a single request handler can give you:

It owns a long-lived resource — a database pool, a tracer SDK, a queue client, a mailer transport.
It needs to register tokens in DI so services and controllers can @Inject(...) them.
It contributes middleware to a specific phase — before global middleware, after global, after routes.
It needs a shutdown so SIGTERM doesn't drop in-flight work or leak sockets.

The crucial mental shift from "middleware" is that the adapter is created once per process, not once per request. The crucial shift from "plugin" is that it has a typed contract — the AppAdapter interface — and the framework calls each hook for you, in order, with a context object that exposes the DI container.

You will compose multiple adapters for any non-trivial app. The pattern that scales is one adapter per concern, each in its own file, all exported as a single ordered list that the bootstrap entry imports. Construction details stay encapsulated — the entry point doesn't need to know which adapter wires up tracing or which one drains a connection pool. It just hands the array to bootstrap() and lets each adapter's lifecycle run.

That encapsulation is the real win. You can move an adapter between apps, you can unit-test one in isolation, and you can read your boot sequence as a list of names rather than a 200-line index.ts.

The lifecycle, in firing order

Every adapter that satisfies AppAdapter can opt into four hooks. They fire in this order, exactly once per process:

beforeMount — runs before modules register their controllers and routes. This is the slot for adapters that need to inject middleware before the route table exists, or that need to mount their own routes ahead of any user-defined handler. An OpenAPI/Swagger UI adapter is a typical example: it wires /docs and /openapi.json here so they sit in front of any catch-all.
beforeStart — runs after all modules have registered, after routes are mounted, and before the HTTP server begins listening. This is the canonical spot to construct resources and call container.registerInstance(TOKEN, value). By the time the first request arrives, every downstream resolve() will see the registered value. Most of your adapter logic lives here.
middleware() — called once at adapter-setup time and returns an array of { phase, handler } entries. The closures it returns are captured, so they can read fields populated in beforeStart lazily, at request time. Phases let you target the slot you actually want — beforeGlobal, afterGlobal, or afterRoutes.
onRouteMount — fires per controller as routes are registered. Most adapters ignore it; collectors (OpenAPI metadata, route inventories) use it to walk every controller as the framework discovers it.

After every adapter's beforeStart finishes, the server starts listening and request handling begins. There is no afterStart hook in the interface — the lifecycle splits naturally between "before listen" (boot) and "after listen" (every request that follows).

shutdown — runs on SIGTERM/SIGINT. The framework calls every adapter's shutdown() concurrently under Promise.allSettled, so a slow drain in one adapter doesn't starve the others, and a thrown error doesn't skip later adapters' cleanup.

That last point is the killer feature. Before adapters, the typical Node app had its own process.on('SIGTERM') block somewhere in index.ts, papered over with a Promise.all and a comment apologising for the order. With adapters, every concern that owns a resource brings its own teardown along, and the framework runs them all without you wiring it up.

Why ordering matters

Adapters are an ordered list, not a bag. Hooks fire in registration order — beforeMount for adapter 0, then 1, then 2; same for beforeStart. Get the order wrong and an upstream adapter hasn't published its DI token by the time a downstream adapter tries to read it, or — worse — auto-instrumentation hooks don't get applied to modules that already imported the un-patched version.

A few generic rules of thumb that apply to almost every app:

Observability first. If you use OpenTelemetry auto-instrumentation, its initialisation has to run before the framework imports Express/HTTP. That means the adapter that owns it goes at index 0, and its constructor (not a beforeStart body) fires the init.
Infrastructure (DB, secrets, config) before everything that needs it. Anything that wants to resolve a connection pool from the container in a request handler has to come after the adapter that registered the pool.
Auth before feature modules. A JWT-verifying middleware has to be in place before the controllers it gates start handling traffic. If your auth adapter runs late, you have a window where decorated routes pass through unchecked.
Doc/metadata collectors last. OpenAPI generators rely on every controller having mounted, so an onRouteMount collector should sit at the end of the list.

If you find yourself wanting to "just put this small thing first because it doesn't matter" — don't. The order is the contract.

Two adapter shapes: factory and class

KickJS v5 ships two ways to build an adapter, and both produce the same shape. The framework only cares that the result satisfies AppAdapter.

The class form gives you private fields, a constructor that runs early, and methods you can override or unit-test. Use it whenever your adapter has non-trivial state lifecycle, multiple resources to coordinate, or initialisation that must happen before the framework runs any other code:

export class TracingAdapter implements AppAdapter {
  name = 'TracingAdapter'
  private readonly handle: TracingHandle

  constructor(input: TracingInput) {
    // Init runs here, before bootstrap() patches express/http.
    this.handle = initTracing(input)
  }

  beforeStart({ container }: AdapterContext): void {
    container.registerInstance(LOGGER, this.handle.logger)
  }

  async shutdown(): Promise<void> {
    await this.handle.shutdown()
  }
}

The factory form, defineAdapter<TConfig>(), is much terser when the adapter is essentially "register one thing in DI, maybe drain it on shutdown." It takes a name and a build(config) that returns the lifecycle hooks as a plain object:

const mailerAdapterFactory = defineAdapter<MailerConfig>({
  name: 'MailerAdapter',
  build(config) {
    return {
      beforeStart({ container }) {
        container.registerInstance(MAILER, new Mailer(config))
      },
    }
  },
})

Rule of thumb: factory form for "stateless registrations + maybe a shutdown"; class form when you need a constructor body, multiple private fields, or methods worth testing in isolation. Don't agonise — both are valid forever, and you can swap one for the other without changing how the framework consumes them.

DI registration patterns

Adapters and the DI container are co-designed. The AdapterContext you receive in beforeMount and beforeStart carries the container, and you have two main tools:

container.registerInstance(TOKEN, value) — bind a token to an already-constructed value. Eager, cheap, and the right answer for anything that should be a process-wide singleton: a connection pool, a mailer, a feature-flag client, a metrics emitter. Build it in beforeStart, register it, move on.
container.registerFactory(TOKEN, () => value, scope) — bind a token to a function the container calls at resolution time. Combined with Scope.REQUEST, this is how you give every request its own short-lived value derived from per-request state. The factory closes over whatever long-lived state you need (caches, registries) and reads request context at the moment of resolution.

Per-request factories are the right tool whenever the value depends on something only known at request time — the active tenant, the current user's permissions, a per-request transaction. A typical pattern:

container.registerFactory(
  TENANT_DB,
  () => {
    const tenant = getRequestValue('tenant')
    if (!tenant) throw new Error('TENANT_DB resolved outside a tenant-scoped route')
    return registry.get(tenant.id)
  },
  Scope.REQUEST,
)

The factory hands back a cached client keyed off the active request. Resolving outside a request frame throws with a clear message — a much better failure mode than a silent undefined in a service three layers down.

A useful discipline: every adapter that calls registerInstance should also have a shutdown() that disposes the same value. If you opened it, you drain it. If a registry caches a fleet of pools, the adapter that owns the registry calls closeAll() on the way out, and it does so before the lower-level resource the pools depend on is closed. Order shutdown the same way you'd order init, just in reverse.

Ask yourself before building an adapter

Before reaching for a new adapter, run through these:

Is this truly process-wide? If the work is per-request, write middleware. If it's a one-shot mutation at boot with no teardown, a plugin or a plain function call may be enough.
What do I construct, and where? Constructor (must run before the framework imports anything else) or beforeStart (everything else)?
What tokens do I publish in DI? And does each one have a clear consumer story — eager singleton via registerInstance, or per-request via registerFactory(..., Scope.REQUEST)?
What middleware phase do I need? beforeGlobal, afterGlobal, or afterRoutes? If you can't answer this in one sentence, the phase is probably wrong.
How do I drain it? What's the shutdown order relative to the adapters around me? What do I leak if I skip it?

Get those five right and the lifecycle does the rest. Adapters are the place KickJS expects you to put the boring, important plumbing — and the more you let the lifecycle do the orchestration, the smaller and saner your index.ts stays.

References

From v3 to v5 — Migrating a Production KickJS App, Slice by Slice

Orinda Felix Ochieng — Sat, 25 Apr 2026 03:21:54 +0000

If you maintain a KickJS v3 app, the v5 changelog probably reads like a wall of unfamiliar primitives — defineAdapter, defineHttpContextDecorator, Scope.REQUEST, definePlugin, ContextMeta augmentations. The temptation is to delay: "we'll do it next quarter." This is a conceptual walkthrough of what actually changes between v3 and v5, what to migrate in what order, and where the sharp edges hide. The goal is to leave you with a mental model, not a recipe.

The short version: a v5 bump is worth doing if you're still adding features. Per-request boilerplate shrinks, role decorators become typesafe, the dep tree gets smaller, and your codebase stops drifting away from where the framework's own docs and examples now live. The migration is mechanical but not trivial, and it goes much better as a planned slice-by-slice swarm than as a Saturday afternoon.

The shape of what changes

Three structural shifts define the v3 → v5 jump, with v4 sitting in the middle as a deprecation runway.

Adapters become functional. In v3 every cross-cutting concern — infrastructure, auth, observability, mailer, swagger — was a class implementing an AppAdapter interface with beforeStart and shutdown hooks. v5 introduces defineAdapter, a factory style where an adapter is just an object you assemble inline. The hook surface is similar; the difference is composability. You can return a configured adapter from a function, parameterize it cleanly, and stop fighting class-instance ergonomics in tests.

Per-request context becomes typed. v3 stamped values onto a request object via middleware, and you read them back through guard helpers — requireTenant(ctx), requireUser(ctx) — that threw on missing values and returned unknown on success. v5 introduces contributors via defineHttpContextDecorator. A contributor declares a key, an optional dependsOn graph, and a resolve function that runs once per request before the handler. Combined with a ContextMeta module augmentation, ctx.get('tenant') returns a fully typed value end-to-end, with the missing-value throw centralized rather than copy-pasted at the top of every handler.

Plugins replace bundled goodies. v3 shipped a first-party mailer package. v5 cuts it. The same fate hits a handful of other "kickjs-*" first-party packages that are now BYO via definePlugin. If you don't use those packages this is a non-event; if you do, expect to write a thin provider interface and a small plugin wrapper.

Two smaller-but-loud changes round it out: a request-scoped DI factory (Scope.REQUEST) that lets you inject per-request resources directly instead of wrapping them in helper closures, and an AuthUser augmentation hook that finally makes role decorators like @Roles('admin', 'worker') typecheck against your actual role union.

A sliced migration plan

Treat this as a one-week swarm, not a casual refactor. The slice order matters because each step depends on the interfaces of the previous one — so a revert at any point produces a working app on either side of the cut.

1. Write the plan first. Land a planning doc in the repo with acceptance criteria per slice. The criterion that matters: "test suite green at this commit, app boots either side of the revert." This single rule prevents you from accidentally coupling slice N+1 to the internals of slice N.

2. Bump to the latest v4.x first. Skipping straight to v5 is the single biggest mistake you can make. Roughly half of the deprecations land as v4 warnings, not v5 errors. By the time you're on v5 those warnings are gone, and the only signal that something's miswired is a runtime null. Sit on v4 long enough to read every warning. Then cut.

3. Land typed contributors before touching DI. Contributors should ship before request-scoped factories, because a Scope.REQUEST factory that resolves "the active tenant's database" reads the tenant out of the per-request context that a contributor populates. Get the contributor and its augmentation in first. Replace the in-handler guard helpers afterwards.

4. Migrate request-scoped resources one module at a time. This is where the bulk of the visible cleanup happens. Each module's mutation paths drop their withResource(id, deps, async (handle) => ...) wrappers in favor of @Autowired(RESOURCE) on a use-case field. One commit per module keeps reverts surgical and gives subagents (or pair programmers) clean work boundaries.

5. Port adapters to defineAdapter after the use-cases are clean. Adapters own the DI registrations the contributors and use-cases depend on, so it's easier to convert them once the consumers are already idiomatic v5. Doing it earlier means the adapter has to support both shapes simultaneously.

6. Cut the v5 dependency bump. With everything above already in v5-idiomatic shape against the v4.x compatibility shim, the actual bump is a one-line package.json change plus the AuthUser augmentation that types your role decorators. Boring on purpose.

7. Convert internal plugins last. Any first-party packages or helpers you'd already extracted get wrapped as definePlugin consumers, and any dropped first-party packages (like the mailer) get replaced with your own thin provider plus a plugin wrapper.

A short, generic example of the contributor shape, just to anchor the mental model:

export const LoadCurrentUser = defineHttpContextDecorator({
  key: 'currentUser',
  resolve: (ctx) => {
    if (!ctx.req.user) throw new HttpException(401, 'no auth')
    return ctx.req.user
  },
})

declare module '@forinda/kickjs' {
  interface ContextMeta { currentUser: AuthUser }
}

After that augmentation, ctx.get('currentUser') is typed everywhere. No guard helper, no unknown.

Common gotchas

dependsOn only resolves contributor keys. A natural first instinct is to declare dependsOn: ['user'] on a contributor that needs the authenticated user. If user is stamped by an adapter middleware — which is true for most JWT integrations — the boot will crash, because dependsOn walks the contributor graph and user isn't in it. Adapter middleware runs before the contributor pipeline, which is the whole point of that ordering. Read the value directly off the request inside resolve and skip dependsOn for it.

The deprecated mailer is louder than the docs suggest. If your app sends transactional email, plan for a small extra slice: a MailProvider interface, a console implementation for dev/test, a real implementation (nodemailer or your provider of choice) for staging/prod, all wrapped in definePlugin so consumers register it via bootstrap({ plugins: [...] }). It's roughly an afternoon of work, but it's not "free with the bump."

Test fixtures need contributor registration. Any test harness that boots a mini app — createTestApp and friends — needs to receive contributor registrations explicitly. Forgetting this is the #1 cause of "everything works in dev, every test 400s." Note that the contributor object itself isn't what you pass; the framework exposes a .registration handle for test composition. Standardize a beforeEach that resets the container, otherwise registrations from a previous test leak into the next.

Library version skew during partial migrations. If your codebase pulls in a downstream package that itself depends on KickJS, that package's peer-dep range may not yet cover v5. During the v4 staging slice this is a non-issue. After the v5 cut, you'll either need to update the downstream package or temporarily pin it. Audit your dep graph before the cut, not after.

Process-wide caches versus naive Scope.REQUEST factories. A Scope.REQUEST factory that opens a fresh database pool per request will absolutely melt your connection pooler under load. The v5 way is a small registry — a process-wide map keyed by whatever you scope on — that hands out cached handles. Cache the promise, not the resolved handle, so concurrent first-resolves don't race. Drain the registry on adapter shutdown.

Don't share working trees across parallel migration agents. If you're dispatching multiple subagents (or human collaborators) to migrate modules in parallel, give each one its own git worktree. A helper-deletion job and a module-migration job sharing a tree will eventually delete a file the other one is still importing, and you'll lose half an hour figuring out why a clean build is suddenly red.

The wins

Compile-time @Roles. Augment AuthUser with your project's role union, and @Roles('admin', 'manager') becomes a typecheck. @Roles('mananger') becomes a compile error. This alone prevents a class of 403-in-prod bug that was historically only catchable via integration tests. It's the single change most worth shipping.

A smaller dependency tree. Dropping the bundled mailer (and, if applicable, any other first-party packages you weren't really using) reduces install size and unlocks a pnpm dedup you might have been carrying. Not glamorous, but real.

Idiomatic v5 patterns compound. Use-case bodies stop with eight lines of plumbing and start with the actual domain logic. New engineers can read a use-case without first learning the framework's wrapper conventions. Per-request DI means future features that need a new scoped resource (a tenant cache, a request-tied audit log, a feature-flag client) plug in through the same Scope.REQUEST factory shape — you write the pattern once and reuse it.

Better request latency on warm paths. The cached request-scoped resources mean a second request for the same scope skips lookups, secret fetches, and pool warmups. Concretely, expect tens of milliseconds shaved off cold paths and a handful off warm ones. It shows up in P95.

Should you do this?

If you're on v3 and shipping new feature work weekly, yes. Plan a focused week, slice the work as described above, and treat the v4 stop as non-negotiable. The win is real and the pattern carries forward to every feature you ship after.

If your v3 codebase is feature-frozen — nothing new in flight, just maintenance — skip it. The migration costs more than the marginal cleanup wins if you aren't writing new use-cases.

If you're starting a new app today, start on v5. Write contributors and defineAdapter from day one, augment AuthUser with your role union before your first @Roles decorator, and write a Scope.REQUEST factory the first time you reach for a request-scoped resource. You'll thank yourself the first time tsc catches a typo that would otherwise have shipped.

Slice by slice is the only sane way through. Smaller commits would be busywork, bigger ones would make reverts catastrophic, and the v4 staging slice catches roughly half the breakage before it can become a runtime mystery. Plan it, dispatch it, and merge it when every slice tip is green.

DEV Community: Orinda Felix Ochieng

Building Custom Context Decorators in KickJS

The two factories

The options surface

Five places to register a contributor

Reading the value back

Errors and recovery

Three patterns worth stealing

A note on type safety

Testing

References

The KickJS Lifecycle — Bootstrap, Runtime, Shutdown

The three phases

The setup phase, step by step

Within-phase ordering

Runtime: the per-request frame

Shutdown: parallel and best-effort

HMR: the dev-mode caveat

App-scoped vs request-scoped state

References

KickJS Asset Manager — Type-Safe File Resolution from Dev to Dist

The shape of the problem

The mental model: a manifest plus a typed proxy

The four ways to consume an asset

1. The ambient nested proxy

2. useAssets() — the hook factory

3. @Asset() — the class field decorator

4. resolveAsset() — the dynamic escape hatch

Build → manifest → runtime

Type safety via typegen

Testing — fixture swapping

When to reach for it

References

Dependency Injection in KickJS — Tokens, Scopes, and the Per-Request Factory

The four DI surfaces

Tokens vs classes

Singleton vs Scope.REQUEST

Adapter-side registration

The per-request factory pattern

The test seam

Putting it together

References

Type-Safe Augmentation Patterns in KickJS — ContextMeta, AuthUser, PolicyRegistry

The general pattern

ContextMeta — typed ctx.get()

AuthUser['roles'] — typed @Roles

PolicyRegistry — typed @Can

The defineAugmentation() catch

Where to put augmentation files

Why this matters

References

The KickJS CLI Toolbox — Generators, Typegen, and the Configurable Build

Lifecycle — the build tool that happens to ship with the framework

Generators — kick g is the codegen surface

The unusual ones, paragraph by paragraph

kick g scaffold and the field DSL

kick g auth-scaffold

kick tinker

kick explain

kick mcp

kick g agents

Packages — kick add is not a synonym for pnpm install

Diagnostics & DX — the bits other CLIs ship as third-party tools

Quality — the CI gate

What makes this CLI different

References

BYO in KickJS v5 — Building Your Own Mailer (and Why That's a Good Thing)

What got deprecated and why

Recipe, not package

The four pieces

What the types look like

The service stays small on purpose

A console provider for dev

The adapter factory

The test seam

Dev to prod is one constructor swap

When you should still ship a package

Why this is better

References

Adapters vs Plugins in KickJS v5 — Choosing the Right Primitive

2. `useAssets()` — the hook factory

3. `@Asset()` — the class field decorator

4. `resolveAsset()` — the dynamic escape hatch

ContextMeta — typed `ctx.get()`

AuthUser['roles'] — typed `@Roles`

PolicyRegistry — typed `@Can`

The `defineAugmentation()` catch

Generators — `kick g` is the codegen surface

`kick g scaffold` and the field DSL

`kick g auth-scaffold`

`kick tinker`

`kick explain`

`kick mcp`

`kick g agents`

Packages — `kick add` is not a synonym for `pnpm install`

Contributors: typed `ctx.get()`

Augmenting `ContextMeta`

The `dependsOn` trap