DEV Community: Orinda Felix Ochieng

Route flags, context decorators and typed assets in KickJS: declare it once, use it everywhere

Orinda Felix Ochieng — Tue, 15 Sep 2026 15:56:35 +0000

Every API accumulates the same kind of glue. "This endpoint is public" gets written three times — once for auth, once for CSRF, once for rate limiting — and two of those are path strings that break the day someone renames a route. "Who is the current user" becomes req.user as any. "Where is the welcome email template" becomes __dirname arithmetic that works in dev and fails in the Docker image.

KickJS has three features that remove that glue, and they are far more useful together than apart:

Feature	What it answers	Mental model
Route flags	What is true about this route?	A fact, written once on the route, read by anything. No behaviour.
Context decorators	What do we know about this request?	A typed value computed per request, before the handler runs.
Asset manager	Where is that file?	A typed path to a file shipped with your code, correct in dev and in the build.

This guide explains each one, then builds a small feature set that uses all three at once: public and private routes, a signed-in user, plan-gated endpoints, per-route rate limits, and locale-aware emails and reports rendered from typed templates.

Versions: @forinda/kickjs 8.4+, @forinda/kickjs-cli 8.2+, @forinda/kickjs-testing 8.0+. All three features are in the core package — nothing extra to install.

1. Route flags: facts about a route

A route flag is a named, inheritable fact about a route. It does nothing by itself; it records something any consumer can read.

// src/flags.ts
import { defineRouteFlag } from '@forinda/kickjs'

export const Public = defineRouteFlag('auth.public')
export const RateLimit = defineRouteFlag<{ rpm: number }>('rate.limit')
export const Feature = defineRouteFlag<string>('billing.feature')

Put flags on a controller, a method, or a module mount. The most specific declaration wins — method > class > mount:

@Public // every route in this controller is public…
@Controller()
export class DocsController {
  @Get('/')
  index(ctx: RequestContext) {} // public

  @Public.off // …except this one
  @Get('/drafts')
  drafts(ctx: RequestContext) {} // not public
}

Read them anywhere you hold a RequestContext — handlers, @Middleware(), guards, contributors:

ctx.route?.flags.has('auth.public') // true / false
ctx.route?.flags.get('rate.limit') // { rpm: 10 } or undefined

Two rules make flags predictable:

Removal is .off, never a falsy value. A flag is either present or absent. @Public.off removes it; there is no "present but false" state that a presence check could misread as "public".
false is a real value. A flag declared with a boolean type can store false, and flags.get() returns it. Only .off removes.

ctx.route is undefined in global middleware, which runs before a route is matched (section 8 shows how pre-routing middleware reads flags anyway).

2. Context decorators: typed values about a request

A context decorator (also called a contributor) computes a value from the request and stores it on the context before the handler runs. It replaces middleware whose only job was "compute X and stash it on the request".

Scaffold one:

kick g contributor locale --dry-run
kick g contributor locale -o src/contributors

Fill it in:

// src/contributors/locale.contributor.ts
import { defineHttpContextDecorator } from '@forinda/kickjs'

// 1. Declare the key's type once, for the whole app.
declare module '@forinda/kickjs' {
  interface ContextMeta {
    locale: { language: string; region: string | null }
  }
}

// 2. Define how it's computed.
export const ResolveLocale = defineHttpContextDecorator({
  key: 'locale',
  resolve: (ctx) => {
    const header = (ctx.req.headers['accept-language'] as string | undefined) ?? 'en'
    const [language, region] = header.split(',')[0].trim().split('-')
    return { language: language.toLowerCase(), region: region ?? null }
  },
})

Use it:

@ResolveLocale
@Get('/home')
home(ctx: RequestContext) {
  const locale = ctx.require('locale') // { language: string; region: string | null }
}

What you get over hand-written middleware:

Concern	Middleware	Context decorator
Type of the value	`(req as any).locale`	`ctx.require('locale')`, typed from `ContextMeta`
Ordering	Array position in `bootstrap()`	`dependsOn: ['user']`, sorted at boot; cycles and missing producers fail startup
Services	`Container.getInstance()` inside the body	`deps: { repo: REPO_TOKEN }`, resolved and typed
Per-route opt-out	Fork the stack or check paths	`skipWhen` / `onlyWhen` with route flags
Errors	Throw → 500	`optional: true`, `onError` fallback, or `HttpException`
Testing	Whole HTTP stack	`runContributor()` against a fake context

Registration sites, highest precedence first: method > class > module contributors() > adapter/plugin contributors() > bootstrap({ contributors }). A narrower registration of the same key silently replaces a broader one.

Reading values:

ctx.require('key') — for values the route must have. Throws MissingContextValueError naming the key and route if the contributor didn't run. Never write ctx.get('key')!: it compiles even after someone deletes the decorator.
ctx.get('key') — for optional extras. Returns T | undefined.
getRequestValue('key') — from a service with no ctx in scope. Returns undefined outside a request.

Always return the value from resolve(). Assigning ctx.locale = … writes to one internal context object that the handler never sees.

3. The asset manager: typed paths to your files

Templates, report layouts, JSON schemas and fixtures live next to your code in development and get copied somewhere else in the build. Without help, every call site does this:

const path =
  process.env.NODE_ENV === 'production'
    ? join(__dirname, '../templates/mails/welcome.ejs')
    : join(__dirname, '../../src/templates/mails/welcome.ejs')

Typos compile, every call site branches on the environment, and __dirname breaks under ESM and bundling.

Configure

Tell the CLI which directories hold assets, in kick.config.ts:

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

export default defineConfig({
  assetMap: {
    mails: { src: 'src/templates/mails', glob: '**/*.ejs' },
    reports: { src: 'src/templates/reports', glob: '**/*.{ejs,html}' },
    schemas: { src: 'src/schemas', glob: '**/*.json' },
  },
})

Each entry takes src (required), dest (default dist/<name>/), glob (default **/*) and keys ('auto', 'strip' or 'with-extension' — how file names become property names).

Generate types

kick typegen   # kick dev runs this automatically on every change

For a file tree like:

src/templates/mails/en/welcome.ejs
src/templates/mails/fr/welcome.ejs
src/templates/reports/monthly.ejs

you get a typed surface:

import { assets } from '@forinda/kickjs'

assets.mails.en.welcome() // absolute path to the right file, dev or build
assets.reports.monthly()
assets.mails.en.welcom() // compile error

Four ways to read an asset

All four go through the same cached resolver:

import { assets, useAssets, Asset, resolveAsset } from '@forinda/kickjs'

assets.reports.monthly() // 1. ambient proxy — the default

class ReportService {
  private assets = useAssets() // 2. as a field — easy to mock in tests
}

@Service()
class InvoiceService {
  @Asset('reports/invoice') // 3. declarative field, resolved on each access
  private invoiceTemplate!: string
}

resolveAsset('mails', 'fr/welcome') // 4. dynamic — names known only at runtime; throws UnknownAssetError on a miss

In the build

kick build copies every assetMap entry into the output directory, writes a manifest (.kickjs-assets.json) and runs typegen. At runtime the resolver uses that manifest when it exists, and walks your src directories when it doesn't — so the same assets.mails.en.welcome() call works in kick dev and in production. After adding a template in dev, kick build:assets refreshes the manifest without a full rebuild.

4. How they fit together

The three features form a natural pipeline for any request:

route matched
   │
   ├─ route flags resolved (method > class > mount)          "what is true about this route"
   │
   ├─ contributors run, in dependsOn order                   "what we know about this request"
   │     • skipWhen / onlyWhen read the flags
   │     • resolve() can read ctx.route.flags values
   │     • guards read flags via exemptWhen
   │
   └─ handler / services
         • ctx.require(...) / getRequestValue(...)
         • assets.* picks the file, often chosen by a contributor value

The division of labour that keeps codebases clean:

Flags describe — "public", "needs the reports feature", "limit 10 rpm". Declarative, inheritable, visible in the route list.
Contributors decide — load the user, load the plan, check the feature, compute the locale. Typed, ordered, testable.
Assets deliver — the template or schema the decision points at, with a path that is always right.

The recipes below build that pipeline piece by piece.

5. Recipe: one "public" flag, every consumer

Declare the fact once:

// src/flags.ts
export const Public = defineRouteFlag('auth.public')

Put it on routes:

@Public
@Controller()
export class AuthController {
  @Post('/login') login(ctx: RequestContext) {}
  @Post('/register') register(ctx: RequestContext) {}

  @Public.off // the only private route here
  @Get('/me')
  me(ctx: RequestContext) {}
}

Now every consumer reads that one declaration instead of its own path list:

// Auth: the user contributor steps aside on public routes (section 6).
skipWhen: 'auth.public'

// CSRF and rate limiting, as route guards:
@Middleware(csrfGuard({ exemptWhen: 'auth.public' }))
@Middleware(rateLimitGuard({ max: 60, exemptWhen: 'auth.public' }))

// OpenAPI: public routes show no lock icon.
SwaggerAdapter({ bearerAuth: true, publicFlag: 'auth.public' })

// The built-in health probes, which you don't own:
bootstrap({ health: { flags: ['auth.public'] } })

Rename a route, change the API prefix, add /users/:id — nothing breaks, because nothing matches on path strings. And DevTools shows each route's resolved flags in its Routes tab, so "why is this endpoint open?" is answered from the route list.

The framework names no flags. auth.public is a name you chose — pick a namespace per concern (auth.*, billing.*, rate.*) so readers can tell who consumes a flag.

6. Recipe: the signed-in user, skipped on public routes

// src/contributors/load-user.contributor.ts
import { defineHttpContextDecorator, HttpException } from '@forinda/kickjs'
import { SESSIONS } from '@/auth/sessions'

declare module '@forinda/kickjs' {
  interface ContextMeta {
    user: { id: string; accountId: string; roles: string[] }
  }
}

export const LoadUser = defineHttpContextDecorator({
  key: 'user',
  skipWhen: 'auth.public', // the flag from section 5
  beforeValidation: true, // answer 401 before 422
  deps: { sessions: SESSIONS },
  resolve: async (ctx, { sessions }) => {
    const user = await sessions.fromToken(ctx.headers.authorization)
    if (!user) throw HttpException.unauthorized()
    return user
  },
})

bootstrap({ modules, contributors: [LoadUser.registration] })

Every route now requires a user, except routes flagged public. Three details matter:

skipWhen makes exemption work across ownership. Without flags, the only way to opt a route out of a contributor is to register a permissive twin under the same key — which you can't do for a contributor a plugin shipped. A flag lives on the route, so you can exempt anything.
beforeValidation: true moves the contributor ahead of body validation. Otherwise an anonymous request with a bad body gets a 422 listing your schema. The order becomes beforeValidation contributors → validation → @Middleware() → other contributors → handler. Read headers and cookies here, never the body — it isn't validated yet.
A skipped contributor sets no key. On routes that can be public, read ctx.get('user'); use ctx.require('user') only where the route is guaranteed private.

Services that need the user don't take it as a parameter:

@Service()
export class AuditService {
  record(action: string) {
    const user = getRequestValue('user') // typed, undefined on public routes
    this.log.insert({ action, userId: user?.id ?? null })
  }
}

7. Recipe: plan-gated routes with a flag value and dependsOn

Goal: some routes require a paid feature. The route states which feature; contributors enforce it.

The flag carries a value:

export const Feature = defineRouteFlag<string>('billing.feature')

Load the account's plan after the user:

// src/contributors/load-plan.contributor.ts
declare module '@forinda/kickjs' {
  interface ContextMeta {
    plan: { name: 'free' | 'pro' | 'enterprise'; features: string[] }
  }
}

export const LoadPlan = defineHttpContextDecorator({
  key: 'plan',
  dependsOn: ['user'], // runs after LoadUser; boot fails if nothing produces 'user'
  skipWhen: 'auth.public',
  deps: { billing: BILLING },
  resolve: async (ctx, { billing }) => billing.planFor(ctx.require('user').accountId),
  onError: () => ({ name: 'free', features: [] }), // billing down → treat as free, don't 500
})

Enforce the feature only where a route asks for one:

// src/contributors/require-feature.contributor.ts
declare module '@forinda/kickjs' {
  interface ContextMeta {
    feature: string
  }
}

export const RequireFeature = defineHttpContextDecorator({
  key: 'feature',
  onlyWhen: 'billing.feature', // routes without the flag skip this entirely
  dependsOn: ['plan'],
  resolve: (ctx) => {
    const needed = ctx.route?.flags.get('billing.feature') // the flag's value, e.g. 'reports'
    const plan = ctx.require('plan')
    if (!needed || !plan.features.includes(needed)) {
      ctx.problem.forbidden({
        type: 'https://example.com/probs/upgrade-required',
        detail: `This needs the ${needed} feature, which is not on the ${plan.name} plan`,
      })
    }
    return needed
  },
})

bootstrap({
  modules,
  contributors: [LoadUser.registration, LoadPlan.registration, RequireFeature.registration],
})

Now gating a route is one line, and it reads like documentation:

@Controller()
export class ReportsController {
  @Feature('reports')
  @Get('/monthly')
  monthly(ctx: RequestContext) {} // pro and above

  @Get('/summary')
  summary(ctx: RequestContext) {} // everyone signed in
}

Why this shape works:

Order is declared, not arranged. dependsOn gives user → plan → feature. Forget LoadUser and the app refuses to start with MissingContributorError instead of failing on the first request.
Cost is paid only where needed. onlyWhen means routes without the flag never evaluate the check; a skipped contributor costs a map lookup.
Errors keep their shape. ctx.problem.forbidden(...) answers RFC 9457 application/problem+json from inside a contributor, so clients can branch on type.
The fallback is explicit. onError returns a value; the runner stores it under the key.

8. Recipe: per-route rate limits from one declaration

A flag with a value, read by several consumers:

export const RateLimit = defineRouteFlag<{ rpm: number }>('rate.limit')

@RateLimit({ rpm: 10 })
@Post('/login')
login(ctx: RequestContext) {}

Inside the route — a guard can exempt unmetered routes with a predicate that reads the value:

@Middleware(
  rateLimitGuard({
    max: 60,
    exemptWhen: ({ flags }) => flags.get('rate.limit')?.rpm === 0,
  }),
)

A contributor can derive the limiter key and window from the same flag:

declare module '@forinda/kickjs' {
  interface ContextMeta {
    rateLimit: { key: string; rpm: number }
  }
}

export const RateLimitKey = defineHttpContextDecorator({
  key: 'rateLimit',
  onlyWhen: 'rate.limit',
  resolve: (ctx) => ({
    key: `${ctx.get('user')?.id ?? ctx.req.ip}:${ctx.route?.path}`,
    rpm: ctx.route?.flags.get('rate.limit')?.rpm ?? 60,
  }),
})

Before routing — app-wide middleware has no ctx.route, so it reads a policy table the app builds at boot from every mounted route's method, path and flags:

bootstrap({ middlewares: [rateLimit({ max: 60, exemptWhen: 'auth.public' })] })

Your own pre-routing middleware can read the same table:

import { bindRoutePolicy, type RoutePolicyTable } from '@forinda/kickjs'

export function accessLog() {
  let policy: RoutePolicyTable | undefined
  const handler = (req, _res, next) => {
    const flags = policy?.lookup(req.method, req.url ?? '/')
    if (!flags?.has('audit.skip')) log.info({ method: req.method, url: req.url })
    next()
  }
  return bindRoutePolicy(handler, (table) => {
    policy = table
  })
}

A request that matches no route matches no flags, and stays limited and logged — which is exactly what you want for scanners probing random paths.

The three shapes a flag test can take

Every skipWhen, onlyWhen and exemptWhen accepts:

'auth.public' // carries this flag
'!auth.public' // does NOT carry it
['auth.public', 'health.probe'] // carries ANY of these
['!auth.public', '!health.probe'] // carries NONE of these
({ flags, route }) => flags.has('a') && flags.has('b') // anything else

A list is single-polarity: ['auth.public', '!metered'] is a compile error, because "any-of" would read it as "public or not metered" while most people read "and". Use a predicate for mixed conditions, and keep predicates cheap — they run per request.

9. Recipe: flag or parameter? Choosing the right tool

Contributors can also take per-call parameters, which overlaps with flags. The rule of thumb:

Use a flag when the fact is read by several consumers, or by tooling (OpenAPI, DevTools), or must be set on routes you don't own.
Use a parameter when it only configures one contributor's behaviour at that call site.

A permission check is a good parameter — only one contributor cares, and the action must be named at every use:

declare module '@forinda/kickjs' {
  interface ContextMeta {
    permission: string
  }
}

export const RequirePermission = defineHttpContextDecorator.withParams<{ action: string }>()({
  key: 'permission',
  dependsOn: ['user'],
  // no paramDefaults.action — every route must name its own action
  resolve: (ctx, _deps, { action }) => {
    if (!ctx.require('user').roles.includes(action)) throw HttpException.forbidden()
    return action
  },
})

@RequirePermission({ action: 'reports:export' }) // ✓
@Get('/export')
export(ctx: RequestContext) {}

@RequirePermission // ✗ compile error: `action` is required

Required parameters have no default on purpose: a placeholder default that one route forgets to override silently gates on the placeholder. For module, adapter or bootstrap registration, use RequirePermission.with({ action: '…' }).registration.

Compare with billing.feature from section 7: that one is a flag because the billing contributor, the OpenAPI spec (to document "requires Pro"), and DevTools all benefit from reading it.

Need	Reach for
"This route is public / metered / exempt"	Flag
"Requires feature X" (and docs should say so)	Flag with a value
"Check permission `reports:export`"	Parameterised contributor
"Load the tenant from a header here, a subdomain there"	Parameterised contributor
Mark routes on a controller from another package	Flag on the module mount

10. Recipe: locale-aware emails from typed templates

Now bring in assets. Keep templates per language:

src/templates/mails/en/welcome.ejs
src/templates/mails/en/password-reset.ejs
src/templates/mails/fr/welcome.ejs

// kick.config.ts
assetMap: {
  mails: { src: 'src/templates/mails', glob: '**/*.ejs' },
},

After kick typegen, assets.mails.en.welcome() and assets.mails['en']['password-reset']() are typed.

The locale contributor (section 2) decides the language per request. The mail service picks the matching template, falling back to English when a translation is missing:

// src/mail/mail.service.ts
import { Service, assets, getRequestValue, resolveAsset, UnknownAssetError } from '@forinda/kickjs'
import ejs from 'ejs'

type MailName = 'welcome' | 'password-reset'

@Service()
export class MailService {
  async render(name: MailName, data: Record<string, unknown>) {
    const language = getRequestValue('locale')?.language ?? 'en'
    return ejs.renderFile(this.templateFor(name, language), data)
  }

  private templateFor(name: MailName, language: string): string {
    try {
      return resolveAsset('mails', `${language}/${name}`) // dynamic: language is runtime data
    } catch (error) {
      if (error instanceof UnknownAssetError) return assets.mails.en[name]() // typed fallback
      throw error
    }
  }
}

Look at who does what:

The contributor turns a header into a typed locale once per request.
The service reads it with getRequestValue — no ctx threaded through three layers.
The asset manager turns fr/welcome into a real path in dev and in the build, and the typed assets.mails.en[name]() fallback means English templates are checked at compile time.

Outside a request (a queue worker, a cron job) getRequestValue returns undefined, and the service falls back to English instead of throwing.

11. Recipe: reports rendered per route

Report templates are a good fit for the @Asset field decorator — fixed files, injected into a service:

// kick.config.ts
assetMap: {
  reports: { src: 'src/templates/reports', glob: '**/*.ejs' },
},

@Service()
export class ReportService {
  @Asset('reports/monthly')
  private monthlyTemplate!: string

  @Asset('reports/invoice')
  private invoiceTemplate!: string

  monthly(data: MonthlyReport) {
    return ejs.renderFile(this.monthlyTemplate, data)
  }
}

Combined with section 7, the controller carries all the policy as declarations:

@Controller()
export class ReportsController {
  @Autowired() private readonly reports!: ReportService

  @Feature('reports') // flag: needs the reports feature
  @RateLimit({ rpm: 5 }) // flag: expensive, limit it
  @ResolveLocale // contributor: formats numbers and dates for the reader
  @Get('/monthly')
  async monthly(ctx: RequestContext) {
    const html = await this.reports.monthly({
      user: ctx.require('user'),
      plan: ctx.require('plan'),
      locale: ctx.require('locale'),
    })
    return ctx.html(html)
  }
}

Reading the decorators top to bottom tells you everything about the endpoint without opening a single middleware file: who can call it, how often, and what context it renders with.

JSON schemas and fixtures work the same way — assets.schemas.webhook() gives a validator the right file in every environment.

12. Recipe: flagging controllers you don't own

Decorators only work on code you can edit. A module can flag routes on any controller it mounts — including one from a package:

// src/modules/webhooks/webhooks.module.ts
import { defineModule } from '@forinda/kickjs'
import { StripeWebhookController } from 'some-payments-package'

export const WebhooksModule = defineModule({
  name: 'WebhooksModule',
  build: () => ({
    routes: () => ({
      path: '/webhooks',
      controller: StripeWebhookController,
      flags: { 'auth.public': true, 'rate.limit': { rpm: 600 } },
    }),
  }),
})

Mount flags are the lowest precedence, so a class or method declaration of the same flag still wins. A list form (flags: ['auth.public']) stores each flag as true.

The same idea covers the framework's own health probes:

bootstrap({ health: { flags: ['auth.public'] } })

Every consumer already reading auth.public — LoadUser, the guards, the OpenAPI spec — now exempts /health/live and /health/ready, with no path strings.

13. Type safety: what the compiler catches

kick typegen (automatic in kick dev) generates three registries into .kickjs/types/:

You write	Typegen generates	The compiler then catches
`defineRouteFlag('rate.limit')` with a value type	`KickRouteFlags`	`skipWhen: 'auth.pubic'` → Did you mean 'auth.public'?; `flags.get('rate.limit')?.rpm` typed, not `unknown`
`declare module … ContextMeta`	— (you write it)	`ctx.require('locale')` typed; `dependsOn: ['usr']` is an error
`assetMap` in `kick.config.ts`	`KickAssets`	`assets.mails.en.welcom()` is an error

And one more that is easy to miss: a deleted decorator becomes a compile error. When a handler is typed with a generated route type, typegen narrows ctx.require() to the keys that route provably has:

@LoadTenant
@RequirePermission({ action: 'audit:read' }) // ← delete this line…
@Get('/audit')
audit(ctx: Ctx<KickRoutes.AuditController['audit']>) {
  return { perm: ctx.require('permission') } // …and this no longer compiles
}

Typegen narrows only when it can prove the whole contributor set. Adapter or plugin contributors() can't be read statically, so projects using them skip the narrowing — ctx.require() still throws at runtime, which is why integration tests stay worth having.

All three registries are opt-in: until you declare your first flag, ContextMeta key or assetMap entry, everything accepts plain strings and keeps compiling.

14. Testing all three

Contributors, in isolation

runContributor from @forinda/kickjs-testing calls a contributor's resolve() against a fake context — no container, no HTTP. Hand it mocked deps and pre-seed upstream keys with initial:

import { describe, expect, it, vi } from 'vitest'
import { runContributor } from '@forinda/kickjs-testing'
import { LoadPlan } from './load-plan.contributor'

describe('LoadPlan', () => {
  it('loads the plan for the signed-in account', async () => {
    const billing = { planFor: vi.fn(async () => ({ name: 'pro', features: ['reports'] })) }

    const { value } = await runContributor(LoadPlan, {
      deps: { billing },
      initial: { user: { id: 'u1', accountId: 'acc-9', roles: [] } }, // what LoadUser would have set
    })

    expect(billing.planFor).toHaveBeenCalledWith('acc-9')
    expect(value).toEqual({ name: 'pro', features: ['reports'] })
  })
})

runContributor calls resolve() directly, so optional and onError paths need the pipeline: build one with buildPipeline([...]) and run it with runContributors(...) from @forinda/kickjs.

Flags, without a request

getRouteFlags(controllerClass, handlerName) returns the same resolved flags a live request sees — method over class over mount:

import { getRouteFlags } from '@forinda/kickjs'

it('keeps /me private while the rest of AuthController is public', () => {
  expect(getRouteFlags(AuthController, 'login').has('auth.public')).toBe(true)
  expect(getRouteFlags(AuthController, 'me').has('auth.public')).toBe(false)
})

A test like this is cheap insurance on the one flag whose removal is a security bug.

The whole pipeline

createTestApp from @forinda/kickjs-testing boots the app with real contributors, flags and ordering; drive it with Supertest and assert the outcomes: 401 without a token, 200 on a public route, 403 with the upgrade problem type on a gated route for a free plan. createTestApp also sets up the request scope, so services calling getRequestValue work in these tests.

Assets, with fixtures

Point the resolver at a fixture manifest and clear its cache:

import { join } from 'node:path'
import { clearAssetCache } from '@forinda/kickjs'

beforeEach(() => {
  process.env.KICK_ASSETS_ROOT = join(__dirname, 'fixtures/assets') // contains .kickjs-assets.json
  clearAssetCache()
})

afterEach(() => {
  delete process.env.KICK_ASSETS_ROOT
  clearAssetCache()
})

@Asset fields resolve on every access, so existing service instances pick up the fixtures without being recreated.

15. Pitfalls

Symptom	Cause	Fix
A "private" route is treated as public	`@Public(false)` style thinking	Remove with `@Public.off`; flags have no false state
`@Public.off` does nothing	The route never inherited the flag	Check where you expected it to come from
Handler sees `undefined` for a contributor value	Assigned `ctx.x = …` in `resolve`/`onError`	Return the value; the runner stores it
`ctx.require('user')` throws on some routes	The contributor was skipped by `skipWhen`	Use `ctx.get('user')` on routes that can be public
Anonymous callers see validation errors	Auth contributor runs after validation	`beforeValidation: true`
`MissingContributorError` at boot	A `dependsOn` key has no producer for that route	Register the producer at the same or broader site
`beforeValidation` contributor fails boot	It depends on a normal contributor	Early contributors may only depend on early ones
Flag test typo matches nothing	Flags not declared yet	Declare with `defineRouteFlag`; typegen narrows every name
`['a', '!b']` won't compile	Lists are single-polarity	Use a predicate
Asset works in dev, missing in production	File not matched by `glob`, or custom `build.outDir`	Widen the glob; set `build.outDir` in `kick.config.ts`
Two files, one asset key	Same basename (`index.html` + `index.pug`)	Default `keys: 'auto'` keeps extensions for that group
New template not found in dev	Manifest is stale	`kick build:assets`
`welcome-email.ejs` needs bracket access	Non-identifier file name	`assets.mails['welcome-email']()`, or rename the file

The CLI commands used

Command	What it does here
`kick g contributor <name>`	Scaffolds a context decorator with its `ContextMeta` stub (`--type bare` for transport-agnostic, `--params "action:string"` for the parameterised form, `-m <module>` to place it in a module).
`kick typegen`	Generates `KickRouteFlags`, route types for `ctx.require()` narrowing, and `KickAssets`.
`kick dev`	Runs the app with hot reload and typegen on every change.
`kick build`	Builds, copies `assetMap` files, writes the asset manifest and runs typegen.
`kick build:assets`	Refreshes the asset manifest without a JS rebuild.
`--dry-run`	Previews any generator's files first.

Recap

Route flags are facts on routes: declared once, inherited method > class > mount, removed with .off, and read by contributors, guards, pre-routing middleware, OpenAPI and DevTools.
Context decorators are typed per-request values: ordered with dependsOn, wired to services with deps, skipped per route with skipWhen / onlyWhen, run early with beforeValidation, parameterised with .withParams.
The asset manager gives typed paths to shipped files: assetMap in config, assets.* in code, correct in dev and in the build.
Together: flags describe the route, contributors decide about the request, assets deliver the file the decision points at — and typegen checks all three.

Build a type-safe tasks API with KickJS and MongoDB, end to end

Orinda Felix Ochieng — Tue, 15 Sep 2026 15:34:15 +0000

Most "todo API" tutorials stop at CRUD. This one builds the parts a real API needs — sign-up and login, per-user data, validation, pagination, filtering, API docs — and keeps one rule the whole way through:

Every concept is defined once, and every layer gets its types from that definition.

No hand-written interface Task that drifts from the database schema. No req.user as any. No request body typed by hope.

We will build a task tracker with KickJS and MongoDB:

users register and log in and get a JWT;
each user manages their own categories and tasks;
tasks support filtering, sorting, search and pagination;
request bodies are validated, and invalid ones never reach your code;
Swagger docs are generated from the same schemas.

The finished code is on GitHub: forinda/kickjs-tasks-app-with-mongodb-ts. Clone it to follow along, or build it from scratch with the steps below.

Versions used: @forinda/kickjs 8.4, @forinda/kickjs-cli 8.2, Mongoose 9, Zod 4, jose 6, Node 22+.

The type-safety map
Scaffold the project
A typed, validated environment
Mongoose models that type themselves
A MongoDB adapter that puts models into DI
Authentication: passwords and tokens
The current user as typed context
Modules, DTOs and controllers
Services: ownership in every query
Listing tasks: pagination, filters, sort and search
Categories
API docs for free
Run it and try it
Where to go next

1. The type-safety map

Keep this picture in mind; every section fills in one line of it.

Zod env schema ───────────────► getEnv('MONGO_URL')                    typed + validated at boot
Mongoose schema ─► Model<T> ──► getModels() ─► Db ─► DbToken ─► @Inject(DbToken) db.Task.find()
Zod DTO ─► fromZod ─► @Post({ body }) ─► kick typegen ─► Ctx<KickRoutes.X['m']> ─► ctx.body
ContextMeta augmentation ─► LoadUser contributor ─► ctx.require('user')
handler return value ─► kick typegen ─► typed route map + OpenAPI schema

The folder layout we end up with:

src/
├── index.ts                     # bootstrap — exports `app`
├── config/index.ts              # Zod env schema
├── adapters/
│   ├── index.ts                 # Swagger + MongoDB adapters
│   └── mongodb.adapter.ts       # connect, register models in DI, health check
├── contributors/
│   └── load-user.contributor.ts # Bearer token → ctx.require('user')
├── db/
│   ├── index.ts                 # getModels(), duplicate-key helper
│   └── models/                  # user, category, task schemas
└── modules/
    ├── index.ts                 # module registry
    ├── auth/                    # register, login, me, token signing
    ├── categories/
    └── tasks/

2. Scaffold the project

Create the project with the KickJS CLI. The flags answer the prompts up front: a minimal template, Express, Zod for schemas, and the Swagger package included.

npx @forinda/kickjs-cli new todo-app --template minimal --runtime express --schema zod --packages swagger --pm pnpm
cd todo-app

Add the libraries this app uses:

pnpm add mongoose jose

mongoose — MongoDB models and queries.
jose — signing and verifying JWTs. (Passwords are hashed with Node's built-in crypto, no extra package.)

You now have src/index.ts, a src/config/index.ts, a kick.config.ts, Vite with hot reload, and kick dev to run it.

From here on, kick is the project's local CLI — run it as pnpm exec kick … or through a package.json script.

src/index.ts stays tiny. It imports the config first (so the env schema is registered before anything reads it), then passes modules and adapters by name:

// src/index.ts
import 'reflect-metadata'
import './config'
import { bootstrap, expressRuntime } from '@forinda/kickjs'
import { modules } from './modules'
import { adapters } from './adapters'

export const app = await bootstrap({ modules, runtime: expressRuntime(), adapters })

3. A typed, validated environment

Configuration bugs are the dullest outages: a typo in MONGO_URL that only shows up on the first request. Validate the environment at boot instead, and get types from the same schema.

// src/config/index.ts
import { loadEnvFromSchema } from '@forinda/kickjs/config'
import { fromZod } from '@forinda/kickjs-schema/zod'
import { z } from 'zod'

const envSchema = fromZod(
  z.object({
    PORT: z.coerce.number().default(3000),
    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
    LOG_LEVEL: z.string().default('info'),
    MONGO_URL: z.url(),
    DB_NAME: z.string().default('mydatabase'),
    JWT_SECRET: z.string().min(32),
  }),
)

// Side effect on purpose: registers the schema before anything reads config.
export const env = loadEnvFromSchema(envSchema)

export default envSchema

What this gives you:

At boot, the app refuses to start if MONGO_URL isn't a URL or JWT_SECRET is shorter than 32 characters.
In code, getEnv('MONGO_URL') is typed string, getEnv('PORT') is a number, and getEnv('MONGO_URLL') is a compile error. kick typegen (run automatically by kick dev) reads the default export to produce those types.

Create .env:

PORT=3000
MONGO_URL=mongodb://localhost:27017
DB_NAME=todo
JWT_SECRET=<paste the output of: openssl rand -hex 32>

4. Mongoose models that type themselves

The Mongoose schema is the single source of truth for what a document looks like. The TypeScript type is inferred from it with InferSchemaType, never written by hand.

The task model

// src/db/models/task.ts
import mongoose, { Schema, type InferSchemaType, type Model } from 'mongoose'

export const TASK_STATUSES = ['todo', 'in_progress', 'done'] as const
export const TASK_PRIORITIES = ['low', 'medium', 'high'] as const

const taskSchema = new Schema(
  {
    userId: { type: Schema.Types.ObjectId, ref: 'User', required: true },
    categoryId: { type: Schema.Types.ObjectId, ref: 'Category', default: null },
    title: { type: String, required: true, trim: true },
    description: { type: String },
    status: { type: String, enum: TASK_STATUSES, default: 'todo' },
    priority: { type: String, enum: TASK_PRIORITIES, default: 'medium' },
    dueDate: { type: Date, default: null },
  },
  { timestamps: true, versionKey: false },
)
taskSchema.index({ userId: 1, status: 1 })

export type Task = InferSchemaType<typeof taskSchema>

// HMR-safe: reuse the compiled model on reload, otherwise OverwriteModelError.
export const MountTaskModel = (connection: typeof mongoose) =>
  (connection.models.Task || connection.model('Task', taskSchema)) as Model<Task>

Three details worth copying:

Enums live in as const arrays (TASK_STATUSES). The schema imports them now; the request DTOs import them in section 8. The database and the API can never disagree about which statuses exist.
Models are created by a function, not at import time. With hot reload, a module can be evaluated twice; calling connection.model('Task', …) a second time throws OverwriteModelError. Reusing connection.models.Task makes reloads safe.
Indexes match your queries. Every task query filters by userId, and the list is often filtered by status.

Users and categories

// src/db/models/user.ts
const userSchema = new Schema(
  {
    name: { type: String, required: true, trim: true },
    email: { type: String, required: true, unique: true, lowercase: true, trim: true },
    passwordHash: { type: String, required: true, select: false }, // never returned unless asked
    role: { type: String, enum: ['user', 'admin'], default: 'user' },
  },
  { timestamps: true, versionKey: false },
)
export type User = InferSchemaType<typeof userSchema>
export const MountUserModel = (connection: typeof mongoose) =>
  (connection.models.User || connection.model('User', userSchema)) as Model<User>

// src/db/models/category.ts
const categorySchema = new Schema(
  {
    userId: { type: Schema.Types.ObjectId, ref: 'User', required: true },
    name: { type: String, required: true, trim: true },
    color: { type: String },
  },
  { timestamps: true, versionKey: false },
)
// Names are unique per user, not globally.
categorySchema.index({ userId: 1, name: 1 }, { unique: true })

export type Category = InferSchemaType<typeof categorySchema>
export const MountCategoryModel = (connection: typeof mongoose) =>
  (connection.models.Category || connection.model('Category', categorySchema)) as Model<Category>

select: false on passwordHash means a plain User.find() never includes it. You have to opt in with .select('+passwordHash'), which you will do in exactly one place: login.

One function collects every model

// src/db/index.ts
import mongoose from 'mongoose'
import { MountCategoryModel } from './models/category'
import { MountTaskModel } from './models/task'
import { MountUserModel } from './models/user'

export const getModels = (connection: typeof mongoose) => ({
  User: MountUserModel(connection),
  Category: MountCategoryModel(connection),
  Task: MountTaskModel(connection),
})

/** MongoDB's duplicate-key error code, for unique indexes. */
export const isDuplicateKeyError = (err: unknown) =>
  (err as { code?: number } | null)?.code === 11000

Its return type becomes the type of "the database" in every service — next section.

5. A MongoDB adapter that puts models into DI

KickJS adapters hook into the app's lifecycle. We want one that connects before the server starts, makes the models injectable, disconnects on shutdown, and reports to the health endpoint.

Generate it

kick g adapter mongodb --dry-run   # shows: src/adapters/mongodb.adapter.ts
kick g adapter mongodb

The generated file has every lifecycle hook stubbed and documented (middleware, beforeMount, beforeStart, afterStart, shutdown, onHealthCheck, …). Keep three: beforeStart, shutdown and onHealthCheck.

Fill it in

// src/adapters/mongodb.adapter.ts
import { defineAdapter, createToken, Logger } from '@forinda/kickjs'
import * as mongoose from 'mongoose'
import { getModels } from '../db'

const logger = Logger.for('MongooseAdapter')

export type Db = ReturnType<typeof getModels>
export const DbToken = createToken<Db>('app/DbModels')

export interface MongodbAdapterConfig {
  uri: string
  dbName?: string
}

/** Hide credentials so connection strings are safe to log. */
const redact = (uri: string) => uri.replace(/\/\/[^@/]*@/, '//***@')

export const MongodbAdapter = defineAdapter<MongodbAdapterConfig>({
  name: 'MongodbAdapter',
  build: (config) => {
    let client: typeof mongoose | null = null

    return {
      async beforeStart(ctx) {
        try {
          client = await mongoose.connect(config.uri, {
            dbName: config.dbName,
            // Fail boot fast instead of the 30 s default when Mongo is unreachable.
            serverSelectionTimeoutMS: 5000,
          })
        } catch (error) {
          // Fail boot: without the models registered, every request would crash instead.
          logger.error(`Failed to connect to MongoDB at ${redact(config.uri)}`, error)
          throw error
        }
        ctx.container.registerInstance(DbToken, getModels(client))
        logger.info(`Connected to MongoDB at ${redact(config.uri)}`)
      },

      async shutdown() {
        await client?.disconnect()
      },

      async onHealthCheck(): Promise<{ name: string; status: 'up' | 'down' }> {
        try {
          if (!client) return { name: 'mongodb', status: 'down' }
          await client.connection.db?.command({ ping: 1 })
          return { name: 'mongodb', status: 'up' }
        } catch {
          return { name: 'mongodb', status: 'down' }
        }
      },
    }
  },
})

Walk through the decisions:

type Db = ReturnType<typeof getModels> — the injectable "database" is exactly the object getModels returns: { User: Model<User>, Category: Model<Category>, Task: Model<Task> }. Add a model to getModels() and every service can use it, fully typed, with no other change.
createToken<Db>(…) — a typed DI token. Injecting it gives you Db, not unknown.
Throw on connection failure. An API that boots without its database answers every request with a 500. Refusing to start makes the problem obvious — in your terminal, or in your orchestrator's crash loop.
serverSelectionTimeoutMS: 5000 — Mongoose otherwise waits 30 seconds before giving up.
redact() — connection strings often contain passwords; never log them raw.
shutdown() runs on graceful shutdown and on every hot reload, so dev reloads don't leak connections.
onHealthCheck() makes MongoDB part of the built-in readiness endpoint.

Register the adapters

// src/adapters/index.ts
import { SwaggerAdapter } from '@forinda/kickjs-swagger'
import { getEnv } from '@forinda/kickjs'
import { MongodbAdapter } from './mongodb.adapter'

export const adapters = [
  SwaggerAdapter({
    info: { title: 'Todo App API', version: '1.0.0' },
  }),
  MongodbAdapter({
    uri: getEnv('MONGO_URL'),
    dbName: getEnv('DB_NAME'),
  }),
]

Any service can now do:

@Inject(DbToken) private readonly db!: Db
// this.db.Task.findOne(...) → typed Task document

6. Authentication: passwords and tokens

Tokens

// src/modules/auth/auth.token.ts
import { getEnv } from '@forinda/kickjs'
import { SignJWT } from 'jose'

export const jwtSecret = () => new TextEncoder().encode(getEnv('JWT_SECRET'))

export const signToken = (userId: string) =>
  new SignJWT()
    .setProtectedHeader({ alg: 'HS256' })
    .setSubject(userId) // the user id lives in `sub`
    .setIssuedAt()
    .setExpirationTime('7d')
    .sign(jwtSecret())

Passwords

Node ships scrypt, a deliberately slow, memory-hard hash designed for passwords. No dependency needed:

// in src/modules/auth/auth.service.ts
import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto'
import { promisify } from 'node:util'

const scryptAsync = promisify(scrypt) as (
  password: string,
  salt: Buffer,
  keylen: number,
) => Promise<Buffer>

async function hashPassword(password: string) {
  const salt = randomBytes(16) // a fresh salt per password
  const hash = await scryptAsync(password, salt, 64)
  return `${salt.toString('hex')}:${hash.toString('hex')}`
}

async function verifyPassword(password: string, stored: string) {
  const [salt, hash] = stored.split(':')
  const expected = Buffer.from(hash, 'hex')
  const actual = await scryptAsync(password, Buffer.from(salt, 'hex'), expected.length)
  return timingSafeEqual(actual, expected) // constant-time comparison
}

timingSafeEqual compares in constant time, so response timing can't reveal how much of a hash matched.

Generate the module

kick g module auth --dry-run
kick g module auth

With the minimal pattern this writes src/modules/auth/auth.module.ts and a controller. Add auth.service.ts, auth.dto.ts and auth.token.ts next to them (kick g service auth -m auth and kick g dto register -m auth scaffold the first two).

The auth service

// src/modules/auth/auth.service.ts
import { HttpException, Inject, Service } from '@forinda/kickjs'
import { DbToken, type Db } from '@/adapters/mongodb.adapter'
import { isDuplicateKeyError } from '@/db'
import type { LoginInput, RegisterInput } from './auth.dto'
import { signToken } from './auth.token'

@Service()
export class AuthService {
  @Inject(DbToken)
  private readonly db!: Db

  async register(input: RegisterInput) {
    try {
      const doc = await this.db.User.create({
        name: input.name,
        email: input.email,
        passwordHash: await hashPassword(input.password),
      })
      const { passwordHash: _, ...user } = doc.toObject()
      return { token: await signToken(String(user._id)), user }
    } catch (err) {
      // The unique index on email did the check — no race between "exists?" and "insert".
      if (isDuplicateKeyError(err)) throw HttpException.conflict('Email already registered')
      throw err
    }
  }

  async login(input: LoginInput) {
    const doc = await this.db.User.findOne({ email: input.email.trim().toLowerCase() })
      .select('+passwordHash')
      .lean()
    // Same error for an unknown email and a wrong password: don't confirm which emails exist.
    if (!doc || !(await verifyPassword(input.password, doc.passwordHash))) {
      throw HttpException.unauthorized('Invalid credentials')
    }
    const { passwordHash: _, ...user } = doc
    return { token: await signToken(String(user._id)), user }
  }

  async me(userId: string) {
    const user = await this.db.User.findById(userId).lean()
    if (!user) throw HttpException.unauthorized('User no longer exists')
    return user
  }
}

Notice what's not there: no "does this email exist?" query before insert. Two sign-ups racing would both pass that check. The unique index is atomic; catching error code 11000 turns it into a clean 409.

7. The current user as typed context

The usual Express approach — a middleware that sets req.user, read later as req.user as any — loses types and fails silently when you forget the middleware. KickJS has context contributors: typed values computed per request, declared on the routes that need them.

Generate it

kick g contributor load-user --dry-run
kick g contributor load-user -o src/contributors

Fill it in

// src/contributors/load-user.contributor.ts
import { defineHttpContextDecorator, HttpException } from '@forinda/kickjs'
import { jwtVerify } from 'jose'
import { jwtSecret } from '@/modules/auth/auth.token'

// 1. Declare the key and its type once, for the whole app.
declare module '@forinda/kickjs' {
  interface ContextMeta {
    user: { id: string }
  }
}

// 2. Define how it's computed.
export const LoadUser = defineHttpContextDecorator({
  key: 'user',
  // Answer 401 before body validation, so anonymous callers can't probe the schema.
  beforeValidation: true,
  resolve: async (ctx) => {
    const header = ctx.req.headers.authorization
    if (!header?.startsWith('Bearer ')) throw HttpException.unauthorized('Missing bearer token')
    try {
      const { payload } = await jwtVerify(header.slice(7), jwtSecret(), { algorithms: ['HS256'] })
      if (!payload.sub) throw new Error('Token has no subject')
      return { id: payload.sub }
    } catch {
      throw HttpException.unauthorized('Invalid or expired token')
    }
  },
})

How it's used:

Put @LoadUser on a controller class (every route) or a single method.
Read ctx.require('user') in the handler. It's typed { id: string } from the ContextMeta declaration.
If you forget @LoadUser, ctx.require('user') throws instead of returning undefined — the bug shows up on the first call, not as a data leak.

Two security details:

algorithms: ['HS256'] — pin the algorithm. Never let the token's own header decide how it's verified.
beforeValidation: true — without it, an anonymous request with a bad body gets a 422 listing the expected fields. With it, they get 401 and learn nothing.

8. Modules, DTOs and controllers

Generate the feature modules

kick g module tasks
kick g module categories

// src/modules/index.ts
import { defineModules } from '@forinda/kickjs'
import { AuthModule } from './auth/auth.module'
import { CategoriesModule } from './categories/categories.module'
import { TasksModule } from './tasks/tasks.module'

export const modules = defineModules()
  .mount(AuthModule())
  .mount(TasksModule())
  .mount(CategoriesModule())

A module declares where its controller is mounted:

// src/modules/tasks/tasks.module.ts
import { defineModule } from '@forinda/kickjs'
import { TasksController } from './tasks.controller'

export const TasksModule = defineModule({
  name: 'TasksModule',
  build: () => ({
    routes() {
      return { path: '/tasks', controller: TasksController }
    },
  }),
})

The file must be named <name>.module.ts — the Vite plugin uses that suffix to hot-reload modules gracefully.

DTOs: one Zod schema, three jobs

Each request body is a Zod schema. The same schema validates at runtime, types the handler and documents the endpoint:

// src/modules/tasks/tasks.dto.ts
import { fromZod } from '@forinda/kickjs-schema/zod'
import { z } from 'zod'
import { TASK_PRIORITIES, TASK_STATUSES } from '@/db/models/task'

const createTaskSchema = z.object({
  title: z.string().trim().min(1).max(200),
  description: z.string().max(5000).optional(),
  status: z.enum(TASK_STATUSES).optional(), // the same array the Mongoose schema uses
  priority: z.enum(TASK_PRIORITIES).optional(),
  dueDate: z
    .union([z.iso.date(), z.iso.datetime({ offset: true })])
    .nullable()
    .optional(),
  categoryId: z
    .string()
    .regex(/^[0-9a-fA-F]{24}$/, 'Invalid id')
    .nullable()
    .optional(),
})

const updateTaskSchema = createTaskSchema.partial()

export const CreateTaskBody = fromZod(createTaskSchema)
export const UpdateTaskBody = fromZod(updateTaskSchema)
export type CreateTaskInput = z.infer<typeof createTaskSchema>
export type UpdateTaskInput = z.infer<typeof updateTaskSchema>

Gotcha: dates. Use ISO strings in DTOs, not z.coerce.date(). A JavaScript Date can't be expressed in JSON Schema, and the Swagger generator silently drops the whole body from the spec. Mongoose casts the string to a Date when it writes.

updateTaskSchema = createTaskSchema.partial() — the update rules can never drift from the create rules.

Controllers: typed handlers from generated types

// src/modules/tasks/tasks.controller.ts
import { ApiQueryParams, Autowired, Controller, Delete, Get, Patch, Post, reply, type Ctx } from '@forinda/kickjs'
import { ApiBearerAuth, ApiTags } from '@forinda/kickjs-swagger'
import { LoadUser } from '@/contributors/load-user.contributor'
import { CreateTaskBody, TASK_QUERY, UpdateTaskBody } from './tasks.dto'
import { TasksService } from './tasks.service'

@ApiTags('Tasks')
@ApiBearerAuth()
@LoadUser // every route below needs a signed-in user
@Controller()
export class TasksController {
  @Autowired() private readonly tasksService!: TasksService

  @ApiQueryParams(TASK_QUERY)
  @Get('/')
  list(ctx: Ctx<KickRoutes.TasksController['list']>) {
    const userId = ctx.require('user').id
    return ctx.paginate((parsed) => this.tasksService.list(userId, parsed), TASK_QUERY)
  }

  @Post('/', { body: CreateTaskBody, name: 'CreateTaskRequest' })
  async create(ctx: Ctx<KickRoutes.TasksController['create']>) {
    return reply(201, await this.tasksService.create(ctx.require('user').id, ctx.body))
  }

  @Get('/:id')
  get(ctx: Ctx<KickRoutes.TasksController['get']>) {
    return this.tasksService.get(ctx.require('user').id, ctx.params.id)
  }

  @Patch('/:id', { body: UpdateTaskBody, name: 'UpdateTaskRequest' })
  update(ctx: Ctx<KickRoutes.TasksController['update']>) {
    return this.tasksService.update(ctx.require('user').id, ctx.params.id, ctx.body)
  }

  @Delete('/:id')
  async remove(ctx: Ctx<KickRoutes.TasksController['remove']>) {
    await this.tasksService.remove(ctx.require('user').id, ctx.params.id)
    return reply.noContent()
  }
}

What's happening:

{ body: CreateTaskBody } attaches the schema. An invalid body gets 422 before your handler runs.
Ctx<KickRoutes.TasksController['create']> — kick typegen (automatic in kick dev) generates KickRoutes from your controllers, so ctx.body is { title: string; status?: 'todo' | 'in_progress' | 'done'; … } and ctx.params.id is a string. Rename a field in the Zod schema and the handler stops compiling.
name: 'CreateTaskRequest' sets the OpenAPI component name. Give every body route a unique PascalCase name; otherwise names derive from handler names (create, update) and collide across controllers.
Return values instead of res.json(). Plain returns become 200 responses; reply(201, …) and reply.noContent() set other statuses. Because handlers return values, typegen can infer every route's response type too.

9. Services: ownership in every query

The most important rule in a multi-user API: a user can only reach their own data. Enforce it in the query itself, not with a separate check.

// src/modules/tasks/tasks.service.ts (the single-item methods)
import { HttpException, Inject, Service, type ParsedQuery } from '@forinda/kickjs'
import { isValidObjectId } from 'mongoose'
import { DbToken, type Db } from '@/adapters/mongodb.adapter'
import type { CreateTaskInput, UpdateTaskInput } from './tasks.dto'

const notFound = () => HttpException.notFound('Task not found')

@Service()
export class TasksService {
  @Inject(DbToken)
  private readonly db!: Db

  async get(userId: string, id: string) {
    if (!isValidObjectId(id)) throw notFound()
    const task = await this.db.Task.findOne({ _id: id, userId }).lean()
    if (!task) throw notFound()
    return task
  }

  async create(userId: string, input: CreateTaskInput) {
    await this.assertCategoryOwned(userId, input.categoryId)
    return (await this.db.Task.create({ ...input, userId })).toObject()
  }

  async update(userId: string, id: string, input: UpdateTaskInput) {
    if (!isValidObjectId(id)) throw notFound()
    await this.assertCategoryOwned(userId, input.categoryId)
    const task = await this.db.Task.findOneAndUpdate({ _id: id, userId }, input, {
      returnDocument: 'after',
      runValidators: true,
    }).lean()
    if (!task) throw notFound()
    return task
  }

  async remove(userId: string, id: string) {
    if (!isValidObjectId(id)) throw notFound()
    const { deletedCount } = await this.db.Task.deleteOne({ _id: id, userId })
    if (!deletedCount) throw notFound()
  }

  private async assertCategoryOwned(userId: string, categoryId: string | null | undefined) {
    if (!categoryId) return
    if (!(await this.db.Category.exists({ _id: categoryId, userId }))) {
      throw HttpException.badRequest('Category not found')
    }
  }
}

The patterns, and why:

{ _id: id, userId } in every query. Someone else's task simply doesn't match. There is no "load, then check the owner" step to forget.
404, not 403, for other users' tasks. A 403 confirms the id exists. A 404 gives nothing away, so ids can't be probed.
isValidObjectId(id) first. A malformed id would otherwise throw a CastError and surface as a 500; it's just "not found".
assertCategoryOwned — without it, a user could attach a task to another user's category id. References need ownership checks too.
runValidators: true — Mongoose skips schema validation on updates by default. Turn it on.
.lean() — returns plain objects instead of full Mongoose documents: faster, and they serialize to JSON cleanly.

10. Listing tasks: pagination, filters, sort and search

KickJS parses list queries for you. Declare which fields may be filtered, sorted and searched:

// src/modules/tasks/tasks.dto.ts
export const TASK_QUERY = {
  filterable: ['status', 'priority', 'categoryId', 'dueDate'],
  sortable: ['createdAt', 'updatedAt', 'dueDate'],
  searchable: ['title', 'description'],
}

In the controller (section 8), ctx.paginate(fetcher, TASK_QUERY) parses the query string into a ParsedQuery — filters, sort, search and pagination, restricted to those fields — calls your fetcher, and wraps what it returns in a standard response:

{
  "data": [ ... ],
  "meta": { "page": 1, "limit": 20, "total": 42, "totalPages": 3, "hasNext": true, "hasPrev": false }
}

@ApiQueryParams(TASK_QUERY) documents the same parameters in Swagger.

The service translates the parsed query into MongoDB:

// src/modules/tasks/tasks.service.ts
const escapeRegex = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')

const COMPARISON = { eq: '$eq', neq: '$ne', gt: '$gt', gte: '$gte', lt: '$lt', lte: '$lte' } as const

/** Translates one `?filter=field:op:value` item into a Mongo condition. */
function toCondition(operator: ParsedQuery['filters'][number]['operator'], raw: string) {
  const value = raw === 'null' ? null : raw
  switch (operator) {
    case 'in':
      return { $in: raw.split(',') }
    case 'between': {
      const [from, to] = raw.split(',')
      return { $gte: from, $lte: to }
    }
    case 'contains':
      return { $regex: escapeRegex(raw), $options: 'i' }
    case 'starts':
      return { $regex: `^${escapeRegex(raw)}`, $options: 'i' }
    case 'ends':
      return { $regex: `${escapeRegex(raw)}$`, $options: 'i' }
    default:
      return { [COMPARISON[operator]]: value }
  }
}

// inside TasksService
async list(userId: string, parsed: ParsedQuery) {
  const filter: Record<string, any> = { userId } // ownership first, always
  for (const { field, operator, value } of parsed.filters) {
    filter[field] = { ...filter[field], ...toCondition(operator, value) }
  }
  if (parsed.search) {
    const regex = { $regex: escapeRegex(parsed.search), $options: 'i' }
    filter.$or = [{ title: regex }, { description: regex }]
  }
  const sort = parsed.sort.length
    ? Object.fromEntries(parsed.sort.map((s) => [s.field, s.direction === 'desc' ? -1 : 1] as const))
    : { createdAt: -1 as const }

  try {
    const [data, total] = await Promise.all([
      this.db.Task.find(filter).sort(sort).skip(parsed.pagination.offset).limit(parsed.pagination.limit).lean(),
      this.db.Task.countDocuments(filter),
    ])
    return { data, total }
  } catch (err) {
    // Bad filter values (e.g. dueDate:gt:tomorrow) fail Mongoose casting.
    if ((err as Error).name === 'CastError') throw HttpException.badRequest('Invalid filter value')
    throw err
  }
}

The details that keep this safe:

userId goes in first, and filters are merged into it — no filter can widen the query to other users.
Only whitelisted fields reach parsed.filters and parsed.sort, so nobody can filter on passwordHash or sort by an unindexed field.
User input in a regex is escaped. Unescaped, ?q=.* matches everything and a crafted pattern can make the database burn CPU.
null means null — ?filter=categoryId:eq:null finds uncategorized tasks.
Casting errors become 400, not 500.
find and countDocuments run in parallel with Promise.all.

What clients can send:

GET /api/v1/tasks?filter=status:eq:done
GET /api/v1/tasks?filter=categoryId:eq:null
GET /api/v1/tasks?filter=dueDate:lt:2026-10-01
GET /api/v1/tasks?sort=dueDate:asc
GET /api/v1/tasks?q=milk
GET /api/v1/tasks?page=2&limit=20

11. Categories

Categories follow the same shape, with two additions.

Duplicate names become 409, straight from the { userId, name } unique index:

async create(userId: string, input: CreateCategoryInput) {
  try {
    return (await this.db.Category.create({ ...input, userId })).toObject()
  } catch (err) {
    if (isDuplicateKeyError(err)) throw HttpException.conflict('Category name already exists')
    throw err
  }
}

Deleting a category keeps its tasks and just uncategorizes them:

async remove(userId: string, id: string) {
  if (!isValidObjectId(id)) throw notFound()
  const { deletedCount } = await this.db.Category.deleteOne({ _id: id, userId })
  if (!deletedCount) throw notFound()
  await this.db.Task.updateMany({ userId, categoryId: id }, { categoryId: null })
}

The DTO validates colors as #RRGGBB:

const createCategorySchema = z.object({
  name: z.string().trim().min(1).max(50),
  color: z.string().regex(/^#[0-9a-fA-F]{6}$/, 'Expected #RRGGBB').optional(),
})

12. API docs for free

The Swagger adapter was registered in section 5. Because every body is a Zod schema with a name, every list route has @ApiQueryParams, and handlers return values, the spec writes itself:

Swagger UI: http://localhost:3000/docs
ReDoc: http://localhost:3000/redoc
Raw spec: http://localhost:3000/openapi.json

@ApiTags('Tasks') groups routes; @ApiBearerAuth() adds the lock icon so you can paste a token and call protected routes from the browser.

13. Run it and try it

Start MongoDB (Docker is quickest) and the API:

docker run -d --name mongo -p 27017:27017 mongo:7
kick dev

The API is at http://localhost:3000/api/v1. Walk through the main flow with curl:

# Register — returns { token, user }
curl -s -X POST http://localhost:3000/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","email":"ada@example.com","password":"correct-horse"}'

TOKEN=<paste the token>

# Create a category
curl -s -X POST http://localhost:3000/api/v1/categories \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Home","color":"#22c55e"}'

# Create a task
curl -s -X POST http://localhost:3000/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"title":"Buy milk","priority":"high","dueDate":"2026-10-01"}'

# List open tasks, soonest first
curl -s "http://localhost:3000/api/v1/tasks?filter=status:eq:todo&sort=dueDate:asc" \
  -H "Authorization: Bearer $TOKEN"

Then try the failure cases — they're the point of the design:

Try	You get
No `Authorization` header	`401`
`POST /tasks` with `{"title":""}`	`422`, with the failing field
Registering the same email twice	`409`
Another user's task id	`404`
`?filter=dueDate:gt:tomorrow`	`400`

The full API:

Method	Path	Notes
`POST`	`/auth/register`	`{ name, email, password }` → `201 { token, user }`
`POST`	`/auth/login`	`{ email, password }` → `{ token, user }`
`GET`	`/auth/me`	Current user
`GET` / `POST`	`/categories`	List / create own categories
`GET` / `PATCH` / `DELETE`	`/categories/:id`	Delete leaves its tasks uncategorized
`GET` / `POST`	`/tasks`	Paginated list / create
`GET` / `PATCH` / `DELETE`	`/tasks/:id`

14. Where to go next

Tests. The project already includes Vitest, Supertest and @forinda/kickjs-testing. Boot the app against a throwaway database with createTestApp({ modules }) and drive it with Supertest. The failure table above is a ready-made list of cases.
A typed frontend client. Typegen already knows every route's body and response type; @forinda/kickjs-client turns that into a typed fetch client, so the response type in your frontend traces back to the Mongoose schema.
Refresh tokens. Seven-day access tokens keep this example simple. For production, pair short-lived access tokens with rotating refresh tokens.
Priority sorting. priority is a string enum, so sorting it would be alphabetical. Add a numeric rank field if you need it.
Narrower query types. Declare TASK_QUERY with as const and the parsed filter and sort field names narrow to literal unions.

The CLI commands used

Command	What it did
`kick new todo-app --template minimal --schema zod --packages swagger`	Created the project with Zod and Swagger ready.
`kick g adapter mongodb`	Scaffolded the database adapter with every lifecycle hook documented.
`kick g module <name>`	Scaffolded the auth, tasks and categories modules.
`kick g service <name> -m <module>` / `kick g dto <name> -m <module>`	Scaffolded services and DTOs inside a module.
`kick g contributor load-user`	Scaffolded the typed current-user contributor.
`--dry-run`	Previewed every generator's files before writing.
`kick dev`	Ran the API with hot reload and automatic typegen.
`kick typegen` / `kick typecheck`	Regenerated route and env types / type-checked.
`kick add <package>`	Adds optional KickJS packages with their dependencies (`kick list --all` for the catalog).

Recap

Env: a Zod schema validates at boot and types getEnv().
Models: Mongoose schemas infer their own types; enums are shared as const arrays; models mount HMR-safely.
DI: an adapter connects, fails fast, and registers getModels() behind a typed token — add a model, get it everywhere.
Auth: scrypt + constant-time comparison, JWTs with a pinned algorithm, one error for every bad login, unique indexes instead of race-prone checks.
Current user: a typed context contributor, not req.user as any, answering 401 before 422.
Requests: one Zod schema validates, types the handler and documents the route.
Data access: ownership inside every query, 404 for anything that isn't yours, escaped regexes, whitelisted filters.
Docs: Swagger generated from the same definitions.

One definition per concept, and the compiler checks the rest.

Realtime in KickJS: WebSockets, rooms, auth and scaling past one server

Orinda Felix Ochieng — Tue, 15 Sep 2026 15:17:58 +0000

Most apps reach a point where "refresh to see changes" stops being acceptable. A new chat message, a comment on a task, a notification — people expect it to appear by itself.

This guide walks through building that in a KickJS API with the official WebSocket package, @forinda/kickjs-ws. It starts from an empty project and ends with a setup you can run on several servers. Every step says what to add, where it goes and why, so you can follow it top to bottom without guessing.

We will build the realtime side of a simple team chat:

people connect once when they open the app;
they subscribe to the rooms (chat channels) they are looking at;
when someone posts a message over the normal HTTP API, everyone watching that room is told;
a person can also get direct events (a mention, an invitation);
when someone is removed, their sockets are closed.

Versions used: @forinda/kickjs 8.4, @forinda/kickjs-ws 7.1, ws 8, Node 22. Names may differ slightly in older versions — check the package's type definitions if something does not line up.

How the pieces fit
Install
Mount the WebSocket adapter
Your first gateway
The message format
Authenticating the handshake
Rooms: subscribing and checking access
Publishing from HTTP routes and services
Put your own interface in front of the transport
Kicking people out
Package it as a plugin
The browser client
Running more than one server
Testing
Troubleshooting checklist

1. How the pieces fit

Before any code, the mental model. There are five parts:

Part	What it is	Lives in
Adapter	`WsAdapter` — attaches a WebSocket server to KickJS's HTTP server and handles upgrades on a path such as `/ws`.	`bootstrap()` (or a plugin)
Gateway	A class decorated with `@WsController('/chat')`. Its methods handle connect, disconnect and named messages — like an HTTP controller, but for sockets.	Your feature module
Rooms	Named groups of sockets. You `join` a socket to `room:42`; broadcasting to `room:42` reaches every socket in it.	`RoomManager`, injected via `WS_ROOM_MANAGER`
Publisher	Your code that says "something happened — tell room X". Usually called from an HTTP use case after a write.	A service you own
Client	A browser `WebSocket` that connects, subscribes and reacts to events.	Your frontend

The flow for "Ada posts a message":

Browser (Ada)                 API                                  Browsers watching room 42
     |  POST /messages  ------> use case saves the row
     |                          publisher.toRoom('room:42', 'message.created', {...})
     |                          RoomManager.broadcast(...)  ------> { event: 'message.created', data }
     | <---- 201 Created

Note what is not there: the message is not sent over the socket. It is saved over plain HTTP, and the socket only carries the news that it happened. That single decision keeps validation, permissions and error handling in one place — your HTTP API — and makes the realtime layer small. We will come back to it.

2. Install

No project yet? The KickJS CLI creates one:

npx @forinda/kickjs-cli new chat-api
cd chat-api

From your KickJS API project, let the CLI add the WebSocket package with its required dependencies:

kick add ws        # installs @forinda/kickjs-ws and ws
pnpm add -D @types/ws

kick add knows each optional package's peers, so you don't have to look them up. To see everything it can add — Swagger, queues, devtools, testing and more — run:

kick list --all

ws is the WebSocket server the adapter uses under the hood. (Installing by hand works too: pnpm add @forinda/kickjs-ws ws.)

Throughout this guide, kick is the project's local CLI (pnpm exec kick …, or through a package.json script).

3. Mount the WebSocket adapter

Open the file where you call bootstrap() (commonly src/index.ts). If you keep adapters in their own folder — a good habit, the entry file stays a list of names — add it there:

// src/adapters/index.ts
import { WsAdapter } from '@forinda/kickjs-ws'

export const adapters = [
  WsAdapter({
    path: '/ws', // upgrade requests to /ws/... are handled
    heartbeatInterval: 30_000, // ping clients; dead connections are dropped
  }),
]

// src/index.ts
import 'reflect-metadata'
import './config'
import { bootstrap, expressRuntime } from '@forinda/kickjs'
import { adapters } from './adapters'
import { modules } from './modules'

export const app = await bootstrap({
  modules,
  adapters,
  runtime: expressRuntime(),
})

Options worth knowing now:

path — the base path. A gateway declared with @WsController('/chat') is reached at /ws/chat.
heartbeatInterval — ping interval in ms; 0 disables it. Keep it on: proxies and phones silently drop idle connections.
maxPayload — the largest message a client may send, in bytes. Set it; a chat event is a few hundred bytes, not megabytes.
auth — handshake authentication (section 6).
broker — relaying broadcasts to other servers (section 13).

At this point the server accepts WebSocket connections on /ws/..., but nothing handles them.

Prefer Socket.IO? Nothing in this guide is different. The same package ships a Socket.IO adapter, and the gateways, decorators, handshake auth and the whole design below carry over unchanged. Install socket.io and swap the adapter:
import { SocketIoAdapter } from '@forinda/kickjs-ws/socket-io'

export const adapters = [
  SocketIoAdapter({
    cors: { origin: 'http://localhost:5173' }, // any Socket.IO server option
    auth: {
      // The token arrives in the client's `auth` option rather than the subprotocol.
      resolveUser: async (_request, handshakeAuth) => {
        const claims = await verifyAccessToken(String(handshakeAuth?.token ?? ''))
        return claims ? { id: claims.sub, userId: claims.sub, sessionId: claims.sid } : null
      },
    },
  }),
]
The same @WsController('/chat') class now serves the Socket.IO namespace /chat, and @OnMessage('subscribe') handles the client's socket.emit('subscribe', data). Handlers receive a SocketIoContext, which mirrors WsContext (data, send, join, leave, to, get, set). The few things that change:

Token: the client passes it as io('/chat', { auth: { token } }); it reaches resolveUser as the second argument, handshakeAuth. A rejected handshake arrives on the client as a connect_error with the message Unauthorized, instead of close code 4401.

Message format: Socket.IO frames events itself, so there is no { event, data } JSON envelope to build or parse — socket.emit(event, data) and socket.on(event, handler).

Rooms belong to a namespace in Socket.IO, where ws rooms are shared across all gateways.

Publishing from services: inject the Socket.IO server with the SOCKET_IO token and call io.of('/chat').to(room).emit(event, data) — WS_ROOM_MANAGER is not registered under this adapter. Your own RealtimeTransport (section 9) hides that difference from the rest of the app.

Reconnection is built into the Socket.IO client, so the hand-written backoff in section 12 is not needed (still refresh the token before it reconnects).

Several servers: use a Socket.IO adapter such as the Redis adapter through the adapter option, instead of broker (section 13).

4. Your first gateway

A gateway is a class. Put it next to the feature it serves. If the feature has no module yet, generate one — the CLI writes the module file and a starter controller (what else it adds depends on your project's pattern; --dry-run shows exactly which files):

kick g module chat --dry-run   # preview the files first
kick g module chat

There is no dedicated gateway generator, so create chat.gateway.ts inside that module by hand:

// src/modules/chat/chat.gateway.ts
import { Service } from '@forinda/kickjs'
import { OnConnect, OnDisconnect, OnMessage, WsController, type WsContext } from '@forinda/kickjs-ws'

@WsController('/chat')
@Service()
export class ChatGateway {
  @OnConnect()
  connect(ctx: WsContext) {
    ctx.send('welcome', { at: new Date().toISOString() })
  }

  @OnMessage('ping')
  ping(ctx: WsContext) {
    ctx.send('pong', ctx.data)
  }

  @OnDisconnect()
  disconnect(_ctx: WsContext) {
    // Rooms are cleaned up for you when a socket closes.
  }
}

Two decorators, two jobs:

@WsController('/chat') tells the adapter "sockets connecting to /ws/chat belong to this class".
@Service() registers it in the DI container, so @Autowired works inside it (you will need that for database access).

Make sure the file is loaded. Decorators run when a file is imported. If nothing imports chat.gateway.ts, the class never registers and connections to /ws/chat do nothing — no error. The simplest fix is to import it from the module file. If your project uses the Vite plugin, an eager glob in the module does it for every file at once:

// src/modules/chat/chat.module.ts
import { defineModule } from '@forinda/kickjs'

// Load every file in this module so decorated classes register.
import.meta.glob(['./**/*.ts', '!./**/*.test.ts'], { eager: true })

export const ChatModule = defineModule({
  name: 'ChatModule',
  build: () => ({ routes: () => [] }),
})

Try it with any WebSocket client (for example npx wscat -c ws://localhost:3000/ws/chat). You should receive welcome, and sending {"event":"ping","data":{"n":1}} should answer pong.

WsContext is what every handler receives. The members you will use most:

Member	Use
`ctx.data`	The `data` of the incoming message. Untrusted — validate it.
`ctx.send(event, data)`	Reply to this socket only.
`ctx.join(room)` / `ctx.leave(room)`	Add or remove this socket from a room.
`ctx.to(room)`	Target a room from inside a handler.
`ctx.broadcast(...)`	Send to the namespace, excluding the sender.
`ctx.get(key)` / `ctx.set(key, value)`	Per-socket storage. The authenticated user lives under `'user'`.

5. The message format

Both directions use the same JSON envelope:

{ "event": "subscribe", "data": { "roomId": "42" } }

Client → server: event picks the @OnMessage('<event>') handler; data becomes ctx.data.
Server → client: ctx.send('subscribed', { roomId: '42' }) arrives as { "event": "subscribed", "data": { "roomId": "42" } }.

Decide on event names early and keep them consistent. A convention that ages well: past tense for things that happened (message.created, member.removed) and imperatives for requests (subscribe, unsubscribe).

6. Authenticating the handshake

An unauthenticated socket that can join any room is a data leak with extra steps. Authenticate once, at connection time, and bind the identity to the socket for its whole life.

6.1 Where does the token go?

A browser cannot set an Authorization header on a WebSocket. You have three options:

Query string (/ws/chat?token=...) — easiest, and the worst: URLs are written to proxy and server access logs, so your token ends up in plain text in log storage.
Cookie — works if your API and app share a site and you already use cookies; you then need CSRF-style origin checks on the upgrade.
Subprotocol — the client passes ['bearer', token] as the second argument to new WebSocket(url, protocols), and it arrives in the Sec-WebSocket-Protocol header. Not logged by default, no cookies needed.

This guide uses the subprotocol.

6.2 Read and verify the token

Write the identity logic as plain functions — no framework types — so they are trivial to unit test:

// src/realtime/socket-identity.ts
import type { IncomingMessage } from 'node:http'
import { verifyAccessToken } from '@/lib/tokens' // your existing JWT verification

export interface SocketIdentity {
  readonly id: string // required by the adapter
  readonly userId: string
  readonly sessionId: string
  readonly [key: string]: unknown
}

/** `Sec-WebSocket-Protocol: bearer, <token>` → `<token>` */
export function tokenFromHandshake(request: IncomingMessage): string | null {
  const raw = request.headers['sec-websocket-protocol']
  const header = Array.isArray(raw) ? raw.join(',') : raw
  if (!header) return null
  const parts = header.split(',').map((p) => p.trim())
  const marker = parts.findIndex((p) => p.toLowerCase() === 'bearer')
  return marker === -1 ? null : (parts[marker + 1] ?? null)
}

export async function resolveSocketIdentity(
  request: IncomingMessage,
): Promise<SocketIdentity | null> {
  const token = tokenFromHandshake(request)
  if (!token) return null
  const claims = await verifyAccessToken(token) // null when invalid or expired
  if (!claims) return null
  return { id: claims.sub, userId: claims.sub, sessionId: claims.sid }
}

Anything else a socket needs to know about its owner — a role, an account id — belongs on this identity too, decided here from the verified token. Never let the client state it in later messages: a client that can say "treat me as user 42" per message is choosing what it reads.

6.3 Plug it into the adapter

WsAdapter({
  path: '/ws',
  auth: {
    resolveUser: (request) => resolveSocketIdentity(request),
    autoJoinUserRoom: true, // joins `user:<id>` automatically; see note below
  },
})

What happens now, per connection:

The upgrade arrives; resolveUser runs before any @OnConnect handler.
It returns null (or throws): the socket is accepted and immediately closed with code 4401. Browsers hide a failed handshake's HTTP status from JavaScript, so a close code is the only thing your client can react to.
It returns an identity: the whole object is stored on the socket as user, and its id as userId.
Messages the client sent while resolveUser was still running are held and delivered after @OnConnect finishes (within limits: 64 messages or 1 MiB).

Read the identity in handlers with ctx.get('user'):

private identity(ctx: WsContext): SocketIdentity | null {
  const user = ctx.get<SocketIdentity>('user')
  return user?.userId ? user : null
}

Gotcha that costs hours: read the user object, not per-field keys like user:userId. The adapter stores the whole object under 'user'. Reading a key it never writes returns undefined, every handler silently returns early, and nothing errors. If "subscribe does nothing", check this first.

About autoJoinUserRoom: it joins each socket to user:<id> so you can message a person directly, and pairs with the package's WS_USER_BROADCASTER helper. It is a perfectly good default. This guide turns it off and joins a user room itself (next section) only so every room name comes from one set of functions.

7. Rooms: subscribing and checking access

7.1 Name rooms deliberately

Room names are a single global namespace across all gateways. Build them with small functions rather than string literals scattered around:

// src/realtime/rooms.ts
export const chatRoom = (roomId: string) => `room:${roomId}`
export const userRoom = (userId: string) => `user:${userId}`
export const sessionRoom = (sessionId: string) => `session:${sessionId}`

The prefix per kind (room:, user:, session:) means a room id and a user id can never land in the same room, however your ids are generated. And because every name comes from these functions, a typo in one place cannot quietly create a room nobody publishes to.

7.2 Join personal rooms on connect

@OnConnect()
connect(ctx: WsContext) {
  const who = this.identity(ctx)
  if (!who) return
  ctx.join(userRoom(who.userId)) // direct events: mentions, invitations
  ctx.join(sessionRoom(who.sessionId)) // lets you close this session's sockets later
}

7.3 Subscribe — and check access every time

The socket proves who someone is. It does not prove what they may see. Check that on every subscribe, against the same rules your HTTP API uses:

@WsController('/chat')
@Service()
export class ChatGateway {
  @Autowired() private readonly rooms!: RoomAccess // your own service wrapping the DB check

  /** `{ "event": "subscribe", "data": { "roomId": "…" } }` */
  @OnMessage('subscribe')
  async subscribe(ctx: WsContext) {
    const who = this.identity(ctx)
    const roomId = this.roomId(ctx)
    if (!who || !roomId) return

    if (!(await this.rooms.mayWatch(who.userId, roomId))) {
      // Say "denied" without saying why — "exists but private" is itself a leak.
      ctx.send('subscribe:denied', { roomId })
      return
    }
    ctx.join(chatRoom(roomId))
    ctx.send('subscribed', { roomId })
  }

  @OnMessage('unsubscribe')
  unsubscribe(ctx: WsContext) {
    const who = this.identity(ctx)
    const roomId = this.roomId(ctx)
    if (who && roomId) ctx.leave(chatRoom(roomId))
  }

  /** Never trust `ctx.data`: check the shape before using it. */
  private roomId(ctx: WsContext): string | null {
    const data = ctx.data as { roomId?: unknown } | undefined
    return typeof data?.roomId === 'string' ? data.roomId : null
  }
}

Why re-check each time instead of caching access on the socket? A socket can stay open for hours. If someone loses access to a private room at 10:00, a cached "allowed" keeps them listening until they happen to reconnect. Reading it per subscribe makes a change take effect on the next subscribe; section 10 covers the ones that must take effect immediately.

A note on dependencies inside gateways. A socket is not an HTTP request, so request-scoped services (anything resolved per request, such as a service that reads the current request's user) are not available in gateway handlers. Inject singletons, and take who is asking from the identity you stored at handshake.

8. Publishing from HTTP routes and services

Now the other direction: something happens in your API and the right sockets should hear about it.

The adapter registers a shared RoomManager under the WS_ROOM_MANAGER token. Inject it anywhere:

import { Autowired, Service } from '@forinda/kickjs'
import { WS_ROOM_MANAGER, type RoomManager } from '@forinda/kickjs-ws'

@Service()
export class PostMessageUseCase {
  @Autowired(WS_ROOM_MANAGER) private readonly roomManager!: RoomManager
  // ...db, validation, etc.

  async execute(roomId: string, authorId: string, body: string) {
    const message = await this.saveMessage(roomId, authorId, body) // the write comes first

    this.roomManager.broadcast(chatRoom(roomId), 'message.created', {
      roomId,
      messageId: message.id,
    })
    return message
  }
}

Three rules make this robust:

Publish after the write succeeds — ideally after the transaction commits. Announcing a message that then rolls back sends clients to fetch something that does not exist.
Never let publishing fail the request. A dropped socket must not turn a saved message into a 500. Wrap the broadcast in try/catch (section 9 puts that in one place).
Send hints, not replicas. { roomId, messageId } rather than the full message with author, reactions and attachments. The client refetches through your HTTP API, which applies permissions and returns the current shape. Your events stay tiny, you never leak a field you forgot to filter, and a client that missed an event recovers by fetching.

Rule 3 deserves emphasis because it removes a whole class of problems. WebSocket delivery is at most once: a phone switching networks misses events. If events carry data, missed events mean wrong screens. If events are hints, the next fetch — on reconnect, on focus, on the next hint — fixes everything.

9. Put your own interface in front of the transport

Injecting RoomManager straight into every use case works, but it spreads the package's API through your codebase and makes section 13 painful. Define the few operations your app actually needs:

// src/realtime/transport.ts
export interface RealtimeEvent {
  readonly type: string // 'message.created'
  readonly payload: Record<string, unknown>
}

export interface RealtimeTransport {
  /** Fire-and-forget: must never throw into the caller. */
  publishToRoom(roomId: string, event: RealtimeEvent): void
  publishToUser(userId: string, event: RealtimeEvent): void
  disconnectUser(userId: string, reason: string): void
  disconnectSession(sessionId: string, reason: string): void
}

Implement it once over the package. kick g service gives you the @Service() class to fill in (-m <module> puts it inside a module instead):

kick g service kick-ws-transport --dry-run

// src/realtime/kick-ws.transport.ts
import { Autowired, Service } from '@forinda/kickjs'
import { WS_ROOM_MANAGER, type RoomManager } from '@forinda/kickjs-ws'
import { chatRoom, sessionRoom, userRoom } from './rooms'
import type { RealtimeEvent, RealtimeTransport } from './transport'

@Service()
export class KickWsTransport implements RealtimeTransport {
  @Autowired(WS_ROOM_MANAGER) private readonly rooms!: RoomManager

  publishToRoom(roomId: string, event: RealtimeEvent) {
    this.send(chatRoom(roomId), event)
  }

  publishToUser(userId: string, event: RealtimeEvent) {
    this.send(userRoom(userId), event)
  }

  disconnectUser(userId: string, reason: string) {
    this.closeRoom(userRoom(userId), reason)
  }

  disconnectSession(sessionId: string, reason: string) {
    this.closeRoom(sessionRoom(sessionId), reason)
  }

  private send(room: string, event: RealtimeEvent) {
    try {
      this.rooms.broadcast(room, event.type, event.payload)
    } catch {
      // Delivery must never fail the write that caused it.
    }
  }

  private closeRoom(room: string, reason: string) {
    try {
      // Copy first: leaving rooms mutates the map we are walking.
      for (const [socketId, socket] of Array.from(this.rooms.getSockets(room) ?? new Map())) {
        this.rooms.leaveAll(socketId)
        socket.close(4403, reason)
      }
    } catch {
      /* same rule */
    }
  }
}

Bind it to a token of your own so callers depend on the interface:

import { createToken } from '@forinda/kickjs'
export const REALTIME = createToken<RealtimeTransport>('app/Realtime/transport')

Use cases now say @Autowired(REALTIME) private readonly realtime!: RealtimeTransport and call this.realtime.publishToRoom(...). Swapping the implementation — for tests, or for a multi-server version — becomes a one-file change.

10. Kicking people out

Access is checked on subscribe (section 7), not on every event. That leaves a gap: someone removed from the team keeps receiving events for rooms they already joined, until they reconnect. Close it explicitly wherever access is taken away:

// in your "remove member" use case, after the removal commits
this.realtime.disconnectUser(userId, 'membership_ended')

// in your "revoke session" / "sign out everywhere" use case
this.realtime.disconnectSession(sessionId, 'session_revoked')

Close codes are how the client learns what happened. WebSocket reserves 4000–4999 for applications. A small, documented set is enough:

Code	Meaning	Client should
`4401`	Handshake rejected (set by the adapter)	Refresh the token, then reconnect
`4403`	Access ended (set by you)	Stop reconnecting; sign out or show a message
anything else	Network, deploy, server restart	Reconnect with backoff

The sessions room from section 7.2 is what makes "revoke one session" possible without disconnecting the person's other devices.

11. Package it as a plugin

You now have an adapter, a transport, a token binding and a gateway that only work together. Registering the adapter without the binding compiles fine and fails on the first publish. A KickJS plugin keeps them as one unit.

11.1 Generate the plugin

Let the CLI write the skeleton. Plugins go to src/plugins by default; -o puts this one next to the rest of the realtime code:

kick g plugin realtime -o src/realtime --dry-run   # shows: src/realtime/realtime.plugin.ts
kick g plugin realtime -o src/realtime

The generated realtime.plugin.ts is a definePlugin() call with every hook stubbed out and documented, so you can see the whole surface before deleting what you don't need. The hooks, in the order KickJS calls them:

Order	Hook	Use it for	In this guide
1	`adapters()`	Adapters the plugin brings; they mount before your own adapters.	`WsAdapter`
2	`register(container)`	DI bindings that modules depend on — runs before modules load.	Bind `REALTIME`
3	`middleware()`	Global connect-style middleware.	Delete
4	`modules()`	Modules the plugin contributes; they load before yours.	Delete (or return a chat module)
5	`contributors()`	Typed per-request values merged into every route.	Delete
6	`onReady(container)`	Work after the app has fully started.	Capture the container
7	`shutdown()`	Cleanup on shutdown and on every hot reload.	Close the broadcaster's connection (section 13)

It also generates a RealtimePluginConfig interface and defaults, so callers can write RealtimePlugin({ path: '/ws' }) if you want the plugin configurable.

Delete the hooks you don't use, then fill in the rest.

11.2 Fill it in

// src/realtime/realtime.plugin.ts
import { definePlugin, type Container } from '@forinda/kickjs'
import { WsAdapter } from '@forinda/kickjs-ws'
import { KickWsTransport } from './kick-ws.transport'
import { resolveSocketIdentity } from './socket-identity'
import { REALTIME, type RealtimeTransport } from './transport'

export const RealtimePlugin = definePlugin({
  name: 'RealtimePlugin',
  build: () => ({
    register(container: Container) {
      // One transport per process.
      let transport: RealtimeTransport | undefined
      container.registerFactory(REALTIME, () => {
        transport ??= container.resolve(KickWsTransport)
        return transport
      })
    },

    adapters: () => [
      WsAdapter({
        path: '/ws',
        maxPayload: 16 * 1024,
        auth: {
          resolveUser: (request) => resolveSocketIdentity(request),
          autoJoinUserRoom: false, // we join our own user and session rooms
        },
      }),
    ],
  }),
})

// src/plugins/index.ts
import { RealtimePlugin } from '@/realtime/realtime.plugin'
export const plugins = [RealtimePlugin()]

// src/index.ts
export const app = await bootstrap({ modules, plugins, adapters, runtime: expressRuntime() })

Two plugin details that trip people up:

Ordering. If resolveUser needs something another plugin binds (a database, a session store), declare dependsOn: ['ThatPlugin'].
Timing. adapters() is built early, before other plugins have registered their bindings. If resolveUser needs a container binding, don't resolve it while building the adapter — capture the container in onReady(container) and resolve lazily inside resolveUser, which only runs when a socket connects:

const runtime: { container: Container | null } = { container: null }

// in build():
onReady(container) { runtime.container = container },
// in resolveUser:
resolveUser: async (request) => {
  const sessions = runtime.container!.resolve(SESSION_STORE) // e.g. to reject revoked sessions
  return resolveSocketIdentity(request, sessions)
},

12. The browser client

A client that survives real networks needs: a token in the subprotocol, resubscription after reconnect, exponential backoff, and special handling for the close codes.

// app/lib/realtime.ts
export type Listener = (event: string, data: Record<string, unknown>) => void

export interface RealtimeConnection {
  subscribe(roomId: string): void
  unsubscribe(roomId: string): void
  close(): void
}

const ACCESS_ENDED = 4403

export function connectRealtime(
  getToken: (fresh: boolean) => Promise<string | null>,
  onEvent: Listener,
): RealtimeConnection {
  let socket: WebSocket | null = null
  let stopped = false
  let attempt = 0
  const watching = new Set<string>() // survives reconnects

  const send = (event: string, data: unknown) => {
    if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ event, data }))
  }

  const open = async () => {
    // On reconnect, ask for a fresh token: the old one may have expired
    // while the socket was up, and the handshake is the only place it's checked.
    const token = await getToken(attempt > 0)
    if (stopped || !token) return

    const scheme = location.protocol === 'https:' ? 'wss' : 'ws'
    const ws = new WebSocket(`${scheme}://${location.host}/ws/chat`, ['bearer', token])
    socket = ws

    ws.addEventListener('open', () => {
      attempt = 0
      for (const roomId of watching) send('subscribe', { roomId }) // resubscribe
    })

    ws.addEventListener('message', (message) => {
      try {
        const { event, data } = JSON.parse(String(message.data))
        onEvent(event, data ?? {})
      } catch {
        /* ignore anything that isn't our envelope */
      }
    })

    ws.addEventListener('close', (closed) => {
      if (stopped) return
      if (closed.code === ACCESS_ENDED) return onEvent('access.ended', {})
      const delay = Math.min(30_000, 500 * 2 ** attempt++) // 0.5s, 1s, 2s … 30s
      setTimeout(() => void open(), delay)
    })
  }

  void open()

  return {
    subscribe(roomId) {
      watching.add(roomId)
      send('subscribe', { roomId })
    },
    unsubscribe(roomId) {
      watching.delete(roomId)
      send('unsubscribe', { roomId })
    },
    close() {
      stopped = true
      socket?.close()
    },
  }
}

One connection per tab, created once when the signed-in part of the app mounts — not one per component. Pages call subscribe(roomId) when they show a room and unsubscribe when they leave.

Turn hints into refetches. With TanStack Query (React, Vue, Solid, Svelte all have adapters), each event invalidates the queries it affects:

const connection = connectRealtime(getToken, (event, data) => {
  switch (event) {
    case 'message.created':
      queryClient.invalidateQueries({ queryKey: ['rooms', data.roomId] })
      break
    case 'notification.created':
      queryClient.invalidateQueries({ queryKey: ['notifications'] })
      break
    case 'access.ended':
      queryClient.clear()
      navigate('/login')
      break
  }
})

Invalidation only refetches queries that are on screen, so a burst of events for a room nobody is looking at costs nothing.

Dev proxy. If your frontend dev server proxies /api to the API, proxy /ws too, with WebSocket support on. For Vite:

server: {
  proxy: {
    '/api': 'http://localhost:3000',
    '/ws': { target: 'ws://localhost:3000', ws: true },
  },
},

13. Running more than one server

Everything so far works on one process. Put two API instances behind a load balancer and it quietly breaks: Ada's socket is on instance A, Bob posts through instance B, and B's RoomManager has never heard of Ada. Room membership lives in the memory of the process holding the socket.

You need every instance to repeat each broadcast to its own sockets. There are two good ways.

Option A: the adapter's broker (simplest)

WsAdapter accepts a broker. The package ships a Redis one (@forinda/kickjs-ws/redis), and the WsBroker interface is small enough to implement over any pub/sub:

interface WsBroker {
  publish(message: WsBrokerMessage): void | Promise<void> // called on every broadcast
  subscribe(onMessage: (message: WsBrokerMessage) => void): void | Promise<void> // once, at startup
  close?(): void | Promise<void>
}

With a broker, RoomManager.broadcast() delivers to local sockets immediately and publishes; other instances deliver to theirs. Each message carries an origin so an instance skips its own. No other code changes.

What a broker does not relay: getSockets(room) and socket closing are per process. disconnectUser from section 10 only closes sockets on the instance that ran it.

Option B: relay your own interface (covers disconnects too)

Because your app talks to RealtimeTransport (section 9), you can wrap the local transport with one that announces every call — publishes and disconnects — to the other instances. If you already run Postgres, LISTEN/NOTIFY needs no new infrastructure:

// src/realtime/broadcast.transport.ts
import { randomUUID } from 'node:crypto'
import postgres from 'postgres'
import type { RealtimeEvent, RealtimeTransport } from './transport'

const CHANNEL = 'app_realtime'
const MAX_PAYLOAD_BYTES = 7500 // NOTIFY payloads are capped at 8000 bytes

type Operation =
  | { op: 'room'; roomId: string; event: RealtimeEvent }
  | { op: 'user'; userId: string; event: RealtimeEvent }
  | { op: 'disconnectUser'; userId: string; reason: string }
  | { op: 'disconnectSession'; sessionId: string; reason: string }

export class BroadcastTransport implements RealtimeTransport {
  private readonly instance = randomUUID() // to skip our own announcements
  private readonly sql: postgres.Sql

  constructor(private readonly local: RealtimeTransport, listenUrl: string) {
    this.sql = postgres(listenUrl, { max: 1 })
    void this.sql.listen(CHANNEL, (payload) => this.receive(payload))
  }

  publishToRoom(roomId: string, event: RealtimeEvent) {
    this.local.publishToRoom(roomId, event) // this instance, now
    this.announce({ op: 'room', roomId, event }) // every other instance
  }

  publishToUser(userId: string, event: RealtimeEvent) {
    this.local.publishToUser(userId, event)
    this.announce({ op: 'user', userId, event })
  }

  disconnectUser(userId: string, reason: string) {
    this.local.disconnectUser(userId, reason)
    this.announce({ op: 'disconnectUser', userId, reason })
  }

  disconnectSession(sessionId: string, reason: string) {
    this.local.disconnectSession(sessionId, reason)
    this.announce({ op: 'disconnectSession', sessionId, reason })
  }

  private announce(operation: Operation) {
    const payload = JSON.stringify({ from: this.instance, ...operation })
    if (Buffer.byteLength(payload) > MAX_PAYLOAD_BYTES) return // hints are tiny; log this
    void this.sql.notify(CHANNEL, payload).catch(() => {
      /* log; never fail the caller */
    })
  }

  private receive(payload: string) {
    try {
      const message = JSON.parse(payload) as Operation & { from: string }
      if (message.from === this.instance) return
      switch (message.op) {
        case 'room':
          return this.local.publishToRoom(message.roomId, message.event)
        case 'user':
          return this.local.publishToUser(message.userId, message.event)
        case 'disconnectUser':
          return this.local.disconnectUser(message.userId, message.reason)
        case 'disconnectSession':
          return this.local.disconnectSession(message.sessionId, message.reason)
      }
    } catch {
      /* ignore malformed payloads */
    }
  }
}

Choose the implementation in the plugin's factory from an environment flag:

container.registerFactory(REALTIME, () => {
  transport ??= process.env.REALTIME_BROADCAST
    ? new BroadcastTransport(container.resolve(KickWsTransport), process.env.REALTIME_LISTEN_URL!)
    : container.resolve(KickWsTransport)
  return transport
})

Keep the factory creating one transport per process — two broadcasters mean two listeners, and every event arrives twice.

Things to know about LISTEN/NOTIFY:

LISTEN holds a session. Point REALTIME_LISTEN_URL straight at Postgres, not through a transaction-mode connection pooler (PgBouncer in transaction mode will silently drop your listener).
At most once. Only listeners connected at that instant hear a notification. That is fine precisely because events are hints (section 8): a missed message.created is repaired by the next fetch, and a missed disconnect is still enforced by your HTTP API refusing the next request.
Small payloads. 8000 bytes maximum. Hints fit easily; if one doesn't, you are sending data instead of hints.

Also check your load balancer: it must support WebSocket upgrades and have an idle timeout longer than your heartbeat interval. Sticky sessions are not required with either option.

14. Testing

Test the layers separately; you do not need a browser for any of it.

Pure functions — token parsing and room names — with plain unit tests:

import { describe, expect, it } from 'vitest'
import { tokenFromHandshake } from './socket-identity'

const request = (protocol?: string) =>
  ({ headers: protocol ? { 'sec-websocket-protocol': protocol } : {} }) as never

describe('tokenFromHandshake', () => {
  it('reads the token after the bearer marker', () => {
    expect(tokenFromHandshake(request('bearer, abc.def'))).toBe('abc.def')
  })
  it('refuses a handshake without one', () => {
    expect(tokenFromHandshake(request())).toBeNull()
    expect(tokenFromHandshake(request('json'))).toBeNull()
  })
})

The transport against a fake RoomManager — assert which room got which event, and that a throwing broadcast does not throw out of publishToRoom:

it('never throws into the caller', () => {
  const transport = new KickWsTransport()
  Object.assign(transport, {
    rooms: { broadcast: () => { throw new Error('socket gone') } },
  })
  expect(() =>
    transport.publishToRoom('t1', 'r1', { type: 'message.created', payload: {} }),
  ).not.toThrow()
})

Use cases by binding REALTIME to a recording fake in your test container, then asserting the use case published the right hint after the write — and nothing when the write fails.

End to end (optional): start the app on a random port, open a ws client with ['bearer', token], send subscribe, trigger the HTTP write, and wait for the event. Keep one or two of these; the layered tests catch almost everything faster.

15. Troubleshooting checklist

Symptom	Likely cause
Connection opens, handlers never run	The gateway file is never imported, so `@WsController` never registered (section 4).
Socket closes immediately with `4401`	`resolveUser` returned `null`: token missing from the subprotocol, expired, or verification threw.
`subscribe` does nothing, no error	Reading identity from the wrong key — use `ctx.get('user')` (section 6.3).
Events reach some users but not others	Two or more instances without a broker/relay (section 13).
Every event arrives twice	Two transports or two listeners created in one process (section 13).
Works locally, drops after ~60 s in production	Load balancer idle timeout shorter than the heartbeat, or no WebSocket support on the proxy.
Removed user still sees new events	No `disconnectUser` call when access is removed (section 10).
Frontend dev server can't connect	The dev proxy is missing `ws: true` for `/ws` (section 12).
A user receives events for a room they never joined	Room names built by hand without a kind prefix, so two different ids produced the same name (section 7.1).

Bonus: the CLI commands that helped along the way

Command	What it did for us
`kick new <name>`	Created the project.
`kick add ws`	Installed the WebSocket package with its required dependencies. `kick list --all` shows everything else it can add.
`kick g module chat`	Scaffolded the feature module the gateway lives in.
`kick g service <name>`	Scaffolded the transport service (`-m <module>` to place it in a module).
`kick g plugin realtime -o src/realtime`	Scaffolded the plugin with every lifecycle hook documented.
`kick g adapter <name>`	Scaffolds your own adapter the same way, if you ever write one (default `src/adapters`).
`--dry-run` / `-f`	On any generator: preview the files, or overwrite existing ones.
`kick dev`	Runs the API with hot reload — which is why `shutdown()` must clean up.
`kick typegen`	Regenerates the typed DI registry and route types.
`kick check` / `kick doctor`	Audits the project for common problems and runs pre-flight checks.
`kick explain "<error>"`	Explains a KickJS error message and suggests a fix.
`kick tinker`	Opens a REPL with the DI container and your services loaded — handy for calling your transport by hand.
`kick rm`	Removes generated code you no longer want.

Run kick --help or kick g --list to see the rest.

Recap

Mount WsAdapter, write gateways with @WsController, and make sure their files load.
Authenticate once at the handshake — token in the subprotocol, never the query string — and bind the identity to the socket.
Name rooms with functions, prefix them by kind, and check access on every subscribe.
Save over HTTP; send small hints over the socket; let clients refetch.
Hide the package behind your own RealtimeTransport, and package adapter + binding + gateway as one plugin.
Close sockets when access ends, with close codes the client understands.
For more than one server, add a broker — or relay your own interface over Redis or Postgres LISTEN/NOTIFY.

That is a realtime layer that stays small, stays correct when the network misbehaves, and scales out without a rewrite.

Cron jobs in KickJS: scheduled work that survives restarts, reloads and multiple servers

Orinda Felix Ochieng — Tue, 15 Sep 2026 15:12:59 +0000

Every real backend grows background work: send the emails that failed, expire old sessions, retry payments, email a weekly digest, clean up rows nobody needs.

KickJS gives you a @Cron decorator to mark a method as scheduled. It deliberately does not pick a scheduler for you — you register an adapter that reads those decorators and runs them. That split is a feature: the scheduling library is one small file you own, and your jobs are ordinary services you can test like anything else.

This guide builds that setup from nothing and then makes it production-ready. Each step says what to add, where, and why, so you can follow along without getting lost.

By the end you will have:

jobs written as normal injectable services with @Cron;
a ~60-line CronAdapter that schedules them with croner;
no overlapping runs, no crashes from a failing job, no duplicate schedules after a hot reload;
patterns for jobs that must run exactly once when you run several API instances;
time-zone-aware schedules;
unit and integration tests.

Versions used: @forinda/kickjs 8.4, croner 9, Node 22. If a name doesn't match in your version, check the package's type definitions.

How it fits together
Install
Cron expressions in two minutes
Write your first job
Build the CronAdapter
Register the adapter
What each safeguard in the adapter is for
Designing job bodies
Running on more than one server
Time zones and "local 7am for every customer"
Turning jobs off for some processes
Testing
Observability
Troubleshooting checklist

1. How it fits together

Three parts:

Part	What it does	Where it lives
`@Cron(expression, options)`	Built into KickJS. Records "run this method on this schedule" as metadata on the class. It does not run anything.	On methods of your job classes
Job class	A normal `@Service()` with injected dependencies and one or more `@Cron` methods.	`src/jobs/*.job.ts`
`CronAdapter`	Yours. At startup, reads each job class's `@Cron` metadata with `getCronJobs()`, creates a schedule for each, and on every tick resolves the job from the DI container and calls the method. Stops everything on shutdown.	`src/adapters/cron.adapter.ts`

At runtime:

bootstrap()
  └─ CronAdapter.beforeStart
       └─ for each job class → getCronJobs(class) → new schedule per @Cron method

every tick
  └─ container.resolve(JobClass) → instance.method()   (errors caught and logged)

shutdown / hot reload
  └─ CronAdapter.shutdown → stop every schedule

2. Install

pnpm add croner

No project yet? Create one with the KickJS CLI first: npx @forinda/kickjs-cli new my-api.

Throughout this guide, kick is the project's local CLI (pnpm exec kick …, or through a package.json script).

croner is a small, dependency-free scheduler with time zone support and built-in overlap protection. Any scheduler works with the same adapter shape; this guide uses croner.

3. Cron expressions in two minutes

KickJS uses the standard 5-field format:

┌──────── minute       (0–59)
│ ┌────── hour         (0–23)
│ │ ┌──── day of month (1–31)
│ │ │ ┌── month        (1–12)
│ │ │ │ ┌ day of week  (0–6, Sunday = 0)
│ │ │ │ │
* * * * *

Expression	Runs
`* * * * *`	Every minute
`/5 * * *`	Every 5 minutes
`0 * * * *`	At the start of every hour
`0,30 * * * *`	On the hour and the half hour
`0 3 * * *`	Every day at 03:00
`0 9 * * 1`	Mondays at 09:00
`0 0 1 * *`	Midnight on the first of each month

Two tips:

Times are in the server's time zone unless you pass timezone (section 10). Servers usually run in UTC; your laptop probably doesn't. Be explicit.
Avoid the top of the hour for heavy jobs if you can — 7 3 * * * instead of 0 3 * * * — so you are not competing with every other system's midnight jobs.

Check an expression with an online cron explainer before shipping it.

4. Write your first job

A job is a service, so start from the service generator. -m places it inside the module whose data it works on:

kick g service session-cleanup -m auth --dry-run   # shows: src/modules/auth/session-cleanup.service.ts
kick g service session-cleanup -m auth

That gives you an injectable @Service() class. Rename or move it if you prefer all jobs in one src/jobs/ folder — the adapter doesn't care where the file lives, only that the class is listed (section 6). Then add a @Cron method. It gets dependencies injected exactly like a controller or use case would:

// src/jobs/session-cleanup.job.ts
import { Autowired, Cron, Service } from '@forinda/kickjs'
import { SessionRepository } from '@/modules/auth/session.repository'

export interface SessionCleanupRun {
  readonly deleted: number
}

@Service()
export class SessionCleanupJob {
  @Autowired() private readonly sessions!: SessionRepository

  @Cron('*/15 * * * *', { description: 'Delete sessions expired more than a day ago' })
  async run(): Promise<SessionCleanupRun> {
    const deleted = await this.sessions.deleteExpiredBefore(new Date(Date.now() - 86_400_000))
    return { deleted }
  }
}

Details worth copying:

@Service() is required. The adapter resolves the job from the DI container on every tick; without @Service() there is nothing to resolve.
@Cron options:
- description — a human-readable label for logs and dashboards.
- timezone — an IANA name such as 'UTC' or 'Africa/Nairobi'.
- runOnInit — also run once immediately at startup. Useful for "catch up after a deploy"; dangerous for anything that sends messages (every restart sends again).
Return a small summary ({ deleted }). The scheduler ignores it, but it makes the job easy to assert on in tests and easy to log.
Keep the logic in services, and keep the job a thin trigger. The same deleteExpiredBefore can then be called from an admin endpoint or a script.

One class can have several @Cron methods if they genuinely belong together; one method per class is usually clearer.

5. Build the CronAdapter

Adapters in KickJS are created with defineAdapter. They get lifecycle hooks — beforeStart runs while the app boots, with access to the container; shutdown runs when the app stops.

5.1 Generate the skeleton

kick g adapter cron --dry-run   # shows: src/adapters/cron.adapter.ts
kick g adapter cron             # -o <dir> to write it elsewhere

The generated file is a defineAdapter() call with a CronAdapterConfig interface, defaults, and every lifecycle hook stubbed and documented — a quick tour of what an adapter can do:

Hook	When it runs	Keep it for cron?
`middleware()`	Returns middleware mounted at named phases (`beforeGlobal`, `beforeRoutes`, …).	No — delete
`beforeMount(ctx)`	Before global middleware; for routes that bypass it (health, docs).	No — delete
`onRouteMount(controller, path)`	Once per controller as routes mount; for route inventories.	No — delete
`beforeStart(ctx)`	After modules and routes are wired, before the server listens. `ctx.container` is ready.	Yes — schedule jobs here
`afterStart(ctx)`	After the server is listening; `ctx.server` is the HTTP server.	No — delete
`contributors()`	Typed per-request context values.	No — delete
`shutdown()`	On graceful shutdown and every hot reload.	Yes — stop every schedule
`onHealthCheck()`	Reports to the built-in `GET /health/ready`.	Optional — e.g. report `down` if jobs are disabled or stuck

Delete everything except beforeStart and shutdown (and onHealthCheck if you want it), add services and enabled to the config, and fill it in as below.

5.2 Fill it in

// src/adapters/cron.adapter.ts
/**
 * Runs `@Cron`-decorated service methods on their schedules.
 *
 * KickJS ships the decorator and leaves the scheduler to the app; `croner` does
 * the timing. Each job is resolved from the container on every tick, so it gets
 * the same singletons a request would. `protect` skips a tick while the previous
 * run is still going, and a failure is logged rather than crashing the process.
 */
import { createLogger, defineAdapter, getCronJobs, type Constructor } from '@forinda/kickjs'
import { Cron as Schedule } from 'croner'

const log = createLogger('Cron')

export interface CronAdapterConfig {
  readonly services: readonly Constructor[]
  /** Off for processes that should never run jobs, like a one-off script. */
  readonly enabled?: boolean
}

export const CronAdapter = defineAdapter<CronAdapterConfig>({
  name: 'CronAdapter',
  defaults: { enabled: true },
  build(config) {
    const scheduled: Schedule[] = []

    return {
      beforeStart(ctx) {
        if (config.enabled === false) return

        for (const service of config.services) {
          for (const job of jobsOf(service)) {
            const label = `${service.name}.${job.handlerName}`

            const schedule = new Schedule(
              job.expression,
              {
                name: label,
                protect: true, // skip a tick while the previous run is still going
                ...(job.timezone ? { timezone: job.timezone } : {}),
              },
              async () => {
                try {
                  const instance = ctx.container.resolve(service) as Record<string, unknown>
                  const handler = instance[job.handlerName]
                  if (typeof handler === 'function') await handler.call(instance)
                } catch (error) {
                  log.error(error, 'Scheduled job failed', { job: label })
                }
              },
            )

            scheduled.push(schedule)
            if (job.runOnInit) void schedule.trigger()
          }
        }
      },

      /** Runs on every hot reload too, so a reload never leaves a second copy ticking. */
      shutdown() {
        for (const schedule of scheduled.splice(0)) schedule.stop()
      },
    }
  },
})

/** The decorator writes to the prototype; read either place so neither detail leaks here. */
export function jobsOf(service: Constructor) {
  const onClass = getCronJobs(service)
  return onClass.length > 0 ? onClass : getCronJobs(service.prototype)
}

getCronJobs() returns, per decorated method, an object like:

{ expression: '*/15 * * * *', handlerName: 'run', description: '...', timezone?: string, runOnInit?: boolean }

That is all the adapter needs.

6. Register the adapter

List the job classes explicitly. An explicit list is easy to read, easy to disable a job from, and means nothing runs just because a file happened to be imported.

If you keep adapters in their own folder (recommended — the entry file stays a list of names):

// src/adapters/index.ts
import { SessionCleanupJob } from '@/jobs/session-cleanup.job'
import { WeeklyDigestJob } from '@/jobs/weekly-digest.job'
import { CronAdapter } from './cron.adapter'

export const adapters = [
  CronAdapter({
    services: [SessionCleanupJob, WeeklyDigestJob],
  }),
]

// src/index.ts
import 'reflect-metadata'
import './config'
import { bootstrap, expressRuntime } from '@forinda/kickjs'
import { adapters } from './adapters'
import { modules } from './modules'

export const app = await bootstrap({
  modules,
  adapters,
  runtime: expressRuntime(),
})

Start the app. A job with * * * * * should log its first run within a minute. If nothing happens, jump to the troubleshooting checklist.

7. What each safeguard in the adapter is for

The adapter is short, but every line prevents a specific production incident.

Resolve the job on every tick

const instance = ctx.container.resolve(service)

Resolving inside the tick (instead of once at startup) means the job always gets the container's current singletons — database pools, mailers, config — exactly as a request would. It also plays well with hot reload in development, where bindings can be replaced.

Jobs run outside any HTTP request. Anything request-scoped (a service that reads the current user, a database chosen from the request's host) is not available. Inject singletons and pass context explicitly.

`protect: true` — no overlapping runs

A job scheduled every minute that occasionally takes three minutes would otherwise start a second and third copy on top of the first. Those copies fight over the same rows, send the same email twice, or exhaust the connection pool. With protect, croner skips a tick while the previous run is still in progress.

This protects against overlap within one process. Across several servers, see section 9.

`try/catch` around every run

An unhandled rejection in a timer callback can crash a Node process — taking your HTTP API down because a cleanup job hit a bad row. Catching and logging keeps one failing job from affecting anything else, and the next tick simply tries again.

Log with a job label so you can find it: { job: 'SessionCleanupJob.run' }.

`shutdown()` stops every schedule

Without it:

In development, every hot reload creates a fresh adapter while the old timers keep ticking. After ten saves, your job runs ten times a minute.
In production, a graceful shutdown waits for timers that will never end, or a job fires while the database pool is closing.

scheduled.splice(0) empties the array while stopping each schedule, so calling shutdown twice is harmless.

8. Designing job bodies

The scheduler is the easy part. These habits make the jobs themselves safe.

Make every job safe to run twice

Deploys restart processes mid-run. Timeouts retry. Someone triggers a job manually. Design for it:

Idempotency keys. "Weekly digest for user 42, week 2026-W37" — store it, and skip if it exists.
Check before acting. "Send reminder where reminded_at is null", then set reminded_at in the same transaction.
Deletes and expiries are naturally idempotent. Deleting already-deleted rows does nothing.

Process in batches

A job that loads every row into memory works on your laptop and falls over on real data:

@Cron('*/5 * * * *', { description: 'Retry failed webhooks' })
async run() {
  let total = 0
  for (;;) {
    const batch = await this.webhooks.claimFailed(100) // at most 100 at a time
    if (batch.length === 0) break
    for (const hook of batch) await this.webhooks.retry(hook)
    total += batch.length
    if (total >= 5_000) break // leave the rest for the next tick
  }
  return { retried: total }
}

A cap per run keeps one tick short, so protect rarely has to skip anything.

Keep jobs thin, logic in services

@Cron('0 * * * *', { description: 'Expire unpaid invoices' })
async run() {
  return await this.invoices.expireUnpaid(new Date())
}

Now expireUnpaid is testable with a fixed date, callable from an admin action, and reused by a migration script — no scheduler involved.

Accept "now" as a parameter

async run(now = new Date()) { ... }

The scheduler calls run() with no arguments, so production uses the real time. Tests call run(new Date('2026-09-14T07:00:00Z')) and never have to fake timers.

9. Running on more than one server

Scale your API to two instances and every instance schedules every job. Two copies of the weekly digest run at 07:00, and every customer gets two emails.

Decide per job which of these it needs.

Pattern 1: fine to run everywhere — claim rows with `SKIP LOCKED`

Queue-like jobs (send pending emails, retry webhooks) can run on every instance at once, as long as two instances never take the same row. Postgres does this with FOR UPDATE SKIP LOCKED:

// Claim up to `limit` rows nobody else holds; mark them as in progress.
const rows = await db.execute(sql`
  update deliveries set status = 'sending', claimed_at = now()
  where id in (
    select id from deliveries
    where status in ('pending', 'failed') and attempts < 5
    order by created_at
    limit ${limit}
    for update skip locked
  )
  returning *
`)

Each instance gets a different slice of the work, and more instances simply drain the queue faster. Add a recovery rule for rows stuck in sending (a crash mid-send): treat claimed_at older than a few minutes as claimable again.

Pattern 2: exactly once — a transaction-scoped advisory lock

Jobs that must run once per tick overall (a digest, a billing run, a report) take a lock first. Postgres advisory locks need no table:

const LOCK_KEY = 6_100_001 // any fixed number, unique per job

@Cron('0 7 * * 1', { description: 'Weekly digest', timezone: 'UTC' })
async run(now = new Date()) {
  return await this.db.transaction(async (tx) => {
    const [row] = await tx.execute(sql`select pg_try_advisory_xact_lock(${LOCK_KEY}) as locked`)
    if (!row?.locked) return null // another instance has it this tick

    // ...the actual work...
    return { sent: 42 }
  })
}

Why this exact variant:

try — returns immediately instead of waiting. The losing instances skip the tick rather than queueing up to run it again afterwards.
xact — the lock is released when the transaction ends, including when the process crashes. A session-level lock held by a dead connection can block the job until the connection times out.
Retries must still be safe (section 8). The lock stops concurrent runs; it does not stop a run that died halfway from being followed by a complete one next tick.

If the work is long, don't hold one giant transaction open for all of it. Use the lock transaction only to claim the run — insert a row like job_runs(job='digest', period='2026-W37') with a unique constraint — commit, then do the work. A duplicate insert means someone else claimed this period.

Not on Postgres? The same two patterns exist elsewhere: SELECT … FOR UPDATE SKIP LOCKED in MySQL 8, or a Redis lock (SET key value NX PX <ttl>) for exactly-once.

Pattern 3: a dedicated worker

At larger scale, run jobs in a separate process: the same codebase, started with jobs enabled, while API instances start with enabled: false (section 11). You still want patterns 1 and 2 — you will eventually run two workers during a deploy.

10. Time zones and "local 7am for every customer"

A fixed zone

For jobs tied to one place, set the zone on the decorator:

@Cron('0 2 * * *', { description: 'Nightly export', timezone: 'Africa/Nairobi' })

croner handles daylight saving transitions for zones that have them. Without timezone, the schedule follows the server's zone — which differs between your laptop, CI and production. Be explicit.

Per-customer local time

"Send each customer their digest at 07:00 their time" cannot be one cron expression, because every customer has a different 07:00. Invert it: tick often, and decide inside the job who is due.

@Cron('0,30 * * * *', { description: 'Digest at each customer’s local hour' })
async run(now = new Date()) {
  const customers = await this.customers.listSubscribed() // each has timezone, weekday, hour

  const due = customers.filter((c) => {
    const local = localWeekdayHour(now, c.timezone)
    // Due in the first half of their local hour, so half-hour zones (UTC+5:30)
    // still get it on the hour they chose, and the other run that hour sends nothing.
    return local.weekday === c.digestWeekday && local.hour === c.digestHour && local.minute < 30
  })

  for (const c of due) await this.digests.sendFor(c, now)
  return { due: due.length }
}

A small helper using the built-in Intl API — no date library needed:

export function localWeekdayHour(at: Date, timeZone: string) {
  const parts = new Intl.DateTimeFormat('en-US', {
    timeZone,
    weekday: 'short',
    hour: 'numeric',
    minute: 'numeric',
    hourCycle: 'h23',
  }).formatToParts(at)
  const get = (type: string) => parts.find((p) => p.type === type)?.value ?? ''
  const weekday = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(get('weekday'))
  return { weekday, hour: Number(get('hour')), minute: Number(get('minute')) }
}

Combine it with an idempotency key per customer and period (section 8) and a lock (section 9), and a retry or a second instance can never double-send.

11. Turning jobs off for some processes

The enabled option exists for processes that boot the app but must not run jobs:

one-off scripts and migrations that import app;
integration tests (you call jobs directly instead);
API instances when a separate worker runs the jobs.

Drive it from configuration:

CronAdapter({
  services: [SessionCleanupJob, WeeklyDigestJob],
  enabled: process.env.RUN_JOBS !== 'false',
})

When jobs are disabled, nothing is scheduled at all, so shutdown has nothing to stop.

12. Testing

Test three separate things. None of them needs to wait for a real clock.

12.1 The adapter reads your decorators

// src/adapters/cron.adapter.test.ts
import 'reflect-metadata'
import { Cron } from '@forinda/kickjs'
import { describe, expect, it } from 'vitest'
import { jobsOf } from './cron.adapter'

class Sample {
  @Cron('*/5 * * * *', { description: 'every five minutes', timezone: 'UTC' })
  async tick() {}
}

describe('cron adapter', () => {
  it('finds @Cron methods on a service class', () => {
    expect(jobsOf(Sample)).toEqual([
      expect.objectContaining({ expression: '*/5 * * * *', handlerName: 'tick', timezone: 'UTC' }),
    ])
  })
})

This catches the silent failure where metadata is written somewhere the adapter doesn't read, so no job ever runs.

12.2 Schedule logic as pure functions

Anything with dates ("is this customer due?") belongs in a pure function with table-driven tests:

it('is due at the customer’s local hour, including half-hour zones', () => {
  const at = new Date('2026-09-14T01:30:00Z') // Monday 07:00 in Asia/Kolkata (UTC+5:30)
  expect(localWeekdayHour(at, 'Asia/Kolkata')).toEqual({ weekday: 1, hour: 7, minute: 0 })
})

Add a daylight-saving case for a zone that has one.

12.3 Jobs, called directly

In integration tests, don't wait for the schedule — resolve the job and call it with a fixed time:

it('sends one digest per owner, and none on a retry', async () => {
  const job = container.resolve(WeeklyDigestJob)
  const monday7am = new Date('2026-09-14T07:00:00Z')

  expect(await job.run(monday7am)).toMatchObject({ digests: 1 })
  expect(await job.run(monday7am)).toMatchObject({ digests: 0 }) // idempotent
})

To test the multi-instance lock, run two calls concurrently with Promise.all and assert that one returned null.

Boot the test app with enabled: false (section 11) so real schedules don't fire in the middle of your tests.

13. Observability

Scheduled work fails quietly — nobody is waiting on a response. Make it visible:

Log a summary per run. Wrap the handler call in the adapter: log the job label, duration and the returned summary at info, errors at error.

  const started = Date.now()
  const result = await handler.call(instance)
  log.info('Scheduled job finished', { job: label, ms: Date.now() - started, result })

Alert on silence, not only on errors. A job that stopped being scheduled logs no errors. Record last_success_at per job (a table row, or a metric) and alert when it is older than a few intervals.
Watch duration. A job creeping from 2 s to 55 s on a one-minute schedule is about to start skipping ticks.
Expose a manual trigger for admins that calls the same service method — handy after an outage, and safe because the job is idempotent.

14. Troubleshooting checklist

Symptom	Likely cause
Job never runs	Class not listed in `CronAdapter({ services })`; adapter not in `bootstrap({ adapters })`; or `enabled` is false.
`No provider for SomethingJob`	Missing `@Service()` on the job class, or its file is never imported.
Job runs at the wrong hour	No `timezone` option and the server isn't in the zone you assumed.
Job runs 2×, 3×, 10× per tick in development	`shutdown` doesn't stop schedules, so hot reloads stack timers.
Job runs twice per tick in production	More than one instance, and the job has no lock or row claiming (section 9).
Job "hangs" and later ticks never run	A run that never resolves (a missing `await`, a stuck query) plus `protect`. Add timeouts to external calls.
One failing job crashed the API	No `try/catch` around the handler call.
Request-scoped dependency is undefined inside a job	Jobs run outside requests; inject singletons and pass context explicitly.
Customers in UTC+5:30 never get the local-hour job	Matching `minute === 0` only; tick every 30 minutes and match the first half of the hour (section 10).

Bonus: the CLI commands that helped along the way

Command	What it did for us
`kick new <name>`	Created the project.
`kick g service <name> -m <module>`	Scaffolded each job class inside the module it belongs to.
`kick g adapter cron`	Scaffolded the scheduler adapter with every lifecycle hook documented.
`kick g plugin <name>`	Scaffolds a plugin the same way, if you later bundle the adapter with DI bindings (default `src/plugins`).
`kick g test <name> -m <module>`	Scaffolds a Vitest file for a job or service.
`--dry-run` / `-f`	On any generator: preview the files, or overwrite existing ones.
`kick dev`	Runs the API with hot reload — which is why `shutdown()` must stop every schedule.
`kick tinker`	Opens a REPL with the DI container and your services loaded — handy for resolving a job and running it once by hand.
`kick typegen`	Regenerates the typed DI registry and route types.
`kick check` / `kick doctor`	Audits the project for common problems and runs pre-flight checks.
`kick explain "<error>"`	Explains a KickJS error message (like `No provider for …`) and suggests a fix.
`kick add <package>`	Adds optional KickJS packages with their dependencies — for example `kick add queue:bullmq` when a job outgrows cron and needs a real queue. `kick list --all` shows the catalog.
`kick rm`	Removes generated code you no longer want.

Run kick --help or kick g --list to see the rest.

Recap

@Cron marks methods; your CronAdapter schedules them — about 60 lines with croner.
Jobs are ordinary @Service() classes: injected, thin, and backed by testable service methods.
The adapter resolves jobs per tick, prevents overlap with protect, catches every error, and stops all schedules on shutdown.
Make every job idempotent and batched; accept now as a parameter.
With several instances, choose per job: claim rows with SKIP LOCKED, or take a transaction-scoped advisory lock for exactly once.
Be explicit about time zones; for per-customer local times, tick often and decide inside the job.
Test the metadata, the date logic and the jobs directly — never by waiting for a clock.

Scheduled work stops being "that script that sometimes runs twice" and becomes part of the application, with the same injection, logging and tests as everything else.

I migrated a 593-route Express app to KickJS twice — here's what held up

Orinda Felix Ochieng — Sun, 06 Sep 2026 14:07:45 +0000

I spent a while moving a large multi-tenant SaaS platform off Express 4 +
Sequelize. The numbers going in:

54 apps, ~593 routes
241 tables across 434 migrations
database-per-tenant — one Postgres database per customer organisation
one 3,046-line controller, and a route table with 26 endpoints that had never once executed

I did it twice. First as a strangler — KickJS mounted inside the running
Express app, serving /api/v2 beside the legacy /api/v1, proven route by route
against the original. Then, once that had taught me what the system actually
does, as a clean rewrite on a fresh KickJS host with Drizzle.

Both runs used the same framework, and that is the thing I want to write about.
Most frameworks are good at one of those two jobs.

Versions throughout: @forinda/kickjs@8.3.1, @forinda/kickjs-cli@8.1.5,
Express 5.1, zod 4, Drizzle 0.45. Code examples use a generic
catalog/orders domain.

The feature that made the strangler possible

A KickJS module's routes() can return a controller or a raw Express router,
and you can mount both under the same path:

routes() {
  return [
    { path: '/catalog', controller: CatalogController }, // the routes I'd converted
    { path: '/catalog', router: legacyCatalogRouter },   // the ones I hadn't
  ]
}

Express takes the first match, so converted routes win and the legacy router
serves the rest. No unconverted route registration has to be copied, and a
route moves across one at a time by adding it to the controller and deleting
nothing.

That is what let a 593-route app migrate incrementally instead of in a big bang.
I haven't found another structured Node framework where "here is an Express
Router, serve it beside my controllers" is a first-class mount.

The inverse also worked, and is undocumented: new Application() + setup()
gives you the pipeline without a listener, and handle() takes raw Node
IncomingMessage/ServerResponse — which is how a KickJS app ran inside an
Express 4 host despite the framework declaring an Express 5 peer.

Context contributors — and how to write one

This is the part I'd steal for any other project. A contributor computes one
typed value per request and publishes it on the context under a key. Here is a
complete one, in the three pieces it always has.

1. Declare the key and its type, by augmenting the framework's registry.
This is what makes ctx.require('actor') typed everywhere downstream:

import { defineHttpContextDecorator, HttpException } from '@forinda/kickjs'

export interface Actor {
  readonly userId: string
  readonly organizationId: string
  readonly isAdmin: boolean
}

declare module '@forinda/kickjs' {
  interface ContextMeta {
    actor: Actor
  }
}

2. Define the resolver. deps pulls services out of the DI container,
dependsOn declares which other contributors must run first, and skipWhen
names the route flags that switch it off entirely:

export const Actor = defineHttpContextDecorator({
  key: 'actor',
  skipWhen: ['auth.public'],
  dependsOn: ['tenantDb'],
  deps: { repo: AUTH_REPOSITORY },
  async resolve(ctx, { repo }): Promise<Actor> {
    const token = bearerToken(ctx.req.headers.authorization)
    if (!token) throw new HttpException(401, 'Authentication required')

    const claims = await verifyAccessToken(token)
    if (!claims) throw new HttpException(401, 'Authentication required')

    return repo.loadActor(claims.sub)
  },
})

Throwing from resolve is the rejection — there's no separate guard step.

3. Register it, either globally in bootstrap({ contributors }), on a module
when every route in it shares the value, or per handler as a decorator:

contributors() {
  return [Actor.registration, TenantDb.registration]
}

Two things earn their keep:

The dependency is declared, so it fails at boot. The legacy app had two
different producers of the same tenant-database key — one from an x-tenant-id
header, one from the bearer token. Declaring dependsOn caught a real bug on the
first run: two routes carried the token-based resolver with no authenticated
user, which would have handed the service undefined at runtime. Missing
dependencies and cycles fail at startup, not per request.

Precedence is method > class > module > adapter > bootstrap. Register once on
the module when every route shares a value; override per handler when one
doesn't. In the rewrite the whole tenant story is a chain the framework
topo-sorts for you — order in the array is irrelevant:

tenantRoute → tenantDb → actor → permissions

Compare with the Express version, which resolved the tenant in the auth
middleware by copying the tenant middleware's logic inline, then wrote the
result to four differently-named request properties. Both are "middleware". Only
one of them tells you when you've wired it wrong.

Parameterised decorators

The same primitive builds a decorator that takes arguments. withParams and
requiredParams are the whole trick:

declare module '@forinda/kickjs' {
  interface ContextKeys {
    // Key-only: the value is the decision, and nothing downstream reads it.
    permissionGranted: true
  }
}

export const RequirePermission = defineHttpContextDecorator.withParams<{
  action: ActionName
  module: ModuleName
}>()({
  key: 'permissionGranted',
  dependsOn: ['permissions'],
  // Makes a bare `@RequirePermission` a boot error rather than a route that
  // silently checks nothing.
  requiredParams: ['action', 'module'],
  resolve(ctx, _deps, params): true {
    const decision = can(ctx.get('permissions'), params.action, params.module)
    if (!decision.allowed) {
      throw new HttpException(403, `Forbidden: ${decision.reason}`)
    }
    return true
  },
})

Used at the point it applies to:

@RequirePermission({ action: 'create', module: 'orders' })
@Post('/')
create(ctx: Ctx<KickRoutes.OrderController['create']>) { … }

Note the ContextMeta / ContextKeys split: ContextMeta when something
downstream reads the value, ContextKeys when the decorator exists only for its
side effect. Both give you compile-time checking on dependsOn strings.

Route flags, and inverting the default

The single highest-value change in the rewrite was three lines:

skipWhen: ['auth.public', 'tenant.controlPlane']

Authentication now rejects by default, and a route opts out explicitly. The
legacy app worked the other way round: you added preAuthorize() to each route
that needed it.

That difference is not theoretical. Porting turned up whole modules where someone
had simply forgotten — every route open, nobody having decided they should be.
Forgetting to add a guard is silent. Forgetting to add auth.public is a 401 on
your first request.

Declaring a flag is one line, and it's worth putting them all in one file:

import { defineRouteFlag } from '@forinda/kickjs'

/** Reachable without a token — login, password reset, health. */
export const Public = defineRouteFlag('auth.public')

/** Deliberately not tenant-scoped — operator console, provisioning. */
export const ControlPlane = defineRouteFlag('tenant.controlPlane')

@Public
@Post('/login')
login(ctx: Ctx<…>) { … }

kick typegen collects every defineRouteFlag call into a KickRouteFlags
registry, so a typo in a skipWhen string is a compile error rather than a
contributor that silently never skips. Flags resolve method > class > mount, same
as contributors, and @Flag.off removes an inherited one.

A flag carries no behaviour of its own — it records a fact that any consumer can
read. That's what makes them composable: the same auth.public is read by the
actor contributor, the audit log and the rate limiter, none of which know about
each other.

Pre-match middleware can read them too

I initially assumed flags were unavailable to connect-style middleware, since
that runs before the router matches and there's no route yet. Wrong — there's an
explicit hand-off:

import { bindRoutePolicy, type RoutePolicyTable } from '@forinda/kickjs'

export function auditUnflagged() {
  let policy: RoutePolicyTable | undefined
  const handler = (req, _res, next) => {
    const flags = policy?.lookup(req.method, req.url ?? '/')
    if (!flags?.has('audit.skip')) log(req.url)
    next()
  }
  return bindRoutePolicy(handler, (table) => { policy = table })
}

lookup() returns an empty map when the path matches no route at all — which
is precisely the traffic you want a rate limiter or an audit log to still see.
The table is handed per-application rather than through a global, so two apps in
one process never see each other's routes.

The split is deliberate, and the pairing is instructive: rateLimit() runs
pre-match because an unmatched surface still needs protecting; csrfGuard() is a
guard because a token check on a route that doesn't exist is meaningless. Having
both forms — and being pointed at the right one by which of them exposes the
table — beats picking one and living with it.

Typed end to end without ceremony

kick typegen walks the modules and generates a KickRoutes namespace. In the
handler you get params, body, query and response typed with no codegen artifacts
in your source:

@Post('/', { body: createOrderSchema, name: 'CreateOrder' })
@ApiTags('Orders')
@RequirePermission({ action: 'create', module: 'orders' })
async create(ctx: Ctx<KickRoutes.OrderController['create']>) {
  return reply.created(await this.orders.create(ctx.body))
}

One zod schema gives you runtime validation and the OpenAPI request body.
ctx.body is inferred from it. The return type flows into
KickRoutes[...].response, which is what makes a generated client know what each
route hands back.

The rewrite currently registers 459 routes and 295 services this way.

A related nicety: handlers return values rather than writing to the response.
reply(status, body) when the status isn't 200, ctx.problem.notFound(...) for
error branches — the latter sends immediately and returns nothing, so failure
cases stay out of the inferred success type.

Adapters as the composition seam

An adapter bundles everything one concern needs — DI registrations, middleware,
contributors, lifecycle hooks, a health probe:

export const TenantAdapter = defineAdapter({
  name: 'TenantAdapter',
  build: (config) => ({
    middleware() { /* connect-style, phase-scoped, path-scoped */ },
    contributors() { return [TenantRoute.registration, TenantDb.registration] },
    beforeStart(ctx) { /* late DI wiring */ },
    async onHealthCheck() { return { name: 'tenant-db', status: 'up' } },
    async shutdown() { /* close what you own */ },
  }),
})

In the legacy app, that same concern was smeared across two middleware files, a
connection registry and four request aliases. Here it's one file you can read top
to bottom.

Phases (beforeGlobal / afterGlobal / beforeRoutes / afterRoutes) and an
optional path scope mean you rarely need to think about ordering.

Drizzle setup and tenant database routing

Database-per-tenant is the part people usually ask about, so here is the whole
mechanism. It is smaller than you'd expect, because the framework supplies the
per-request plumbing and Drizzle supplies the rest.

Two schemas, two migration sets

The schema splits in two. A control database holds routing and identity —
which organisations exist, which hosts point at them, which physical database
each one lives in. A tenant database, one per organisation, holds everything
else.

src/db/schema/control/   organizations, tenant_domains, tenant_db_assignment, …
src/db/schema/tenant/    the actual domain — 240 tables
migrations/control/      0000_control-baseline.sql, …
migrations/tenant/       0000_tenant-baseline.sql, …

Two drizzle-kit configs, because they migrate independently — the control
database once, the tenant migrations across every provisioned tenant:

// drizzle.tenant.config.ts
export default defineConfig({
  schema: './src/db/schema/tenant/index.ts',
  out: './migrations/tenant',
  dialect: 'postgresql',
  casing: 'snake_case',
  dbCredentials: { url: process.env.TENANT_DATABASE_URL ?? '' },
})

Conventions worth locking in early, because retrofitting them across 240 tables
is miserable: one table per file, enums in their own files, and named migrations
only (drizzle-kit generate --name=add-order-table) so git history reads as
something other than timestamps.

Column mixins

Every table is built from the same mixins, which is how you get audit columns
and soft delete without 240 opportunities to forget one. The audit foreign key
is a parameter, since control-side tables point at operator users and tenant-side
tables at tenant users:

export function withAudit(opts: AuditMixinOpts) {
  const target = resolveFk(opts)
  return {
    created_by: auditFk('created_by', target),
    created_at: timestamp('created_at', { withTimezone: true })
      .notNull().default(sql`now()`),
    updated_by: auditFk('updated_by', target),
    updated_at: timestamp('updated_at', { withTimezone: true })
      .notNull().default(sql`now()`),
  }
}

export function withAuditAndSoftDelete(opts: AuditMixinOpts) {
  return {
    ...withAudit(opts),
    deleted_at: timestamp('deleted_at', { withTimezone: true }),
    deleted_by: auditFk('deleted_by', target),
    deletion_reason: text('deletion_reason'),
  }
}

A table then reads:

export const orders = pgTable('orders', {
  id: pk(),
  organization_id: fk('organization_id').notNull(),
  total_minor: bigint('total_minor', { mode: 'bigint' }).notNull(),
  currency: char('currency', { length: 3 }).notNull(),
  ...withAuditAndSoftDelete({ fkColumn: () => users.id }),
})

The fkColumn accepts a thunk so a self-referential table — users.created_by
pointing at users.id — needs no forward declaration.

For the record, the legacy schema carried audit columns in two spellings
(created_by on 175 tables, createdBy on 46) and soft delete on 187 of 241.
Normalising that is a mixin, not a migration project.

Keys are ULIDs, generated client-side with a monotonic factory so ids minted
in the same millisecond still sort in creation order:

export const pk = () =>
  char('id', { length: 26 }).primaryKey().$defaultFn(() => newId())

Postgres has no ULID type, so it's char(26) — ten bytes wider than a uuid, and
readable in a log line without decoding. Generating client-side means children
can link to a parent before either is flushed.

One pool per instance, not per tenant

The connection layer is about forty lines. The important detail is that pools are
cached by connection URL, so a hundred tenants sharing one Postgres instance
share one pool rather than opening a hundred:

const pools = new Map<string, postgres.Sql>()

function poolFor(url: string): postgres.Sql {
  let sql = pools.get(url)
  if (!sql) {
    sql = postgres(url, { max: 10, onnotice: () => {} })
    pools.set(url, sql)
  }
  return sql
}

export function createTenantDb(url: string) {
  return drizzle(poolFor(url), { schema: tenantSchema })
}

The routing table stores an instance URL and a database name separately, so
moving a tenant to another instance is a row update rather than a migration:

export function tenantUrl(instanceUrl: string, dbName: string): string {
  const url = new URL(instanceUrl)
  url.pathname = `/${dbName}`
  return url.toString()
}

Routing a request to its database

Two contributors, and this is where the framework earns its place. The first
answers which organisation:

export const ResolveTenantRoute = defineHttpContextDecorator({
  key: 'tenantRoute',
  skipWhen: 'tenant.controlPlane',
  deps: { router: TENANT_ROUTER },
  async resolve(ctx, { router }): Promise<TenantRoute | null> {
    const headers = ctx.req.headers as Record<string, string | string[] | undefined>
    return router.resolve({
      host: pickHost(headers, { trustProxy: getEnv('TRUST_PROXY') === true }),
      tenantHeader: firstHeader(headers['x-tenant-id']),
    })
  },
})

The second answers which connection, and depends on the first:

export const LoadTenantDb = defineHttpContextDecorator({
  key: 'tenantDb',
  skipWhen: 'tenant.controlPlane',
  dependsOn: ['tenantRoute'],
  deps: { resolver: TENANT_DB_RESOLVER },
  async resolve(ctx, { resolver }): Promise<TenantDb | null> {
    const route = ctx.get('tenantRoute')
    if (!route) return null
    return resolver.forOrg(route.orgId)
  },
})

Four decisions in there are worth stealing:

Host-first, header as a fallback. A host is set by the connection; a header
is set by whoever is calling. The legacy app was header-first, which meant the
tenant selector was fully client-controlled. Keeping x-tenant-id behind a
feature flag is what lets existing clients keep working while hosts roll out.

The header is a selector, not a credential. It says which tenant to route to,
never who is calling. The actor contributor separately checks that the
authenticated user's organisation matches the resolved one — without that, a
header alone would be a tenant-hopping primitive.

Both resolve to null rather than throwing. Control-plane routes legitimately
have no tenant, and they say so with the tenant.controlPlane flag, which
skipWhen reads. A route that genuinely needs a connection is the thing that
turns null into a 400. The legacy middleware answered such requests itself with
a 400, which is why "public" routes there could still be refused for tenant
reasons nobody had asked for.

tenantDb depends on tenantRoute, not on the actor. Unauthenticated tenant
routes — login, password reset — still need their tenant's database. Get this
edge wrong and login is impossible on a per-tenant database.

Downstream, a repository just asks for it:

const db = ctx.require('tenantDb')
return db.select().from(orders).where(eq(orders.organization_id, orgId))

For comparison, the Express version registered a Sequelize connection into a
global model registry per request, keyed by a database name formatted from the
organisation id, in a middleware that also did authentication.

The sharp edges, honestly

A post with no criticism is marketing, so:

@Middleware() is not where Express middleware goes. It's engine-neutral and
calls its handler as (ctx, next). Hand it a connect-style (req, res, next) and
next binds to the response object — you get TypeError: next is not a function,
a 500 whose stack points at your middleware rather than at the mismatch. Express
middleware belongs in an adapter's middleware(). The CLI's generated template
used to get this backwards; it now says so explicitly and points you at
kick g guard.

routes() paths must be literals. Typegen parses them statically, so hoisting
a path into a const leaves the module unbound, every handler generating with
contextKeys: never — and the type errors point at the controller, not at the
module file that caused it. Recognise the symptom:
Property 'x' does not exist on type 'never' on every handler at once.

Both are the same class of problem: the framework has the right answer, but the
shortest path from the symptom doesn't lead to it. Worth knowing up front, which
is most of why I'm writing this.

What the migration itself taught me

Two things I'd carry to any port, framework aside.

Prove parity with a test, not with a compile. Every module in the strangler
run shipped with a test hitting the same route on both API versions and asserting
identical status, body and content-type. It caught genuinely subtle things: a
route registered twice, a PUT /remove/ where all its siblings were DELETE, a
handler returning a different response shape depending on whether a query
string was present.

Beware the heuristic you invented three modules ago. I had a rule for
predicting whether a module was portable — does the handler return a value or
write to the response? It was wrong three times, always in the same direction,
and cost two modules a second pass each. What actually predicts cost is whether
the handler holds its own queries, which is one grep:

grep -c "getDb(\|dbRepo\[" <controllers>

Rewriting rather than transcribing also surfaces far more. The strangler run
accumulated about 30 recorded findings; the rewrite found 194 — because
writing behaviour fresh forces you to read every branch, where transcription
lets you copy straight past them.

Would I pick it again

For this shape of problem — a structured multi-tenant API with real per-request
scoping — yes. The composition layer is the differentiator: contributors,
adapters, flags and mixed mounting are what let the same framework host both an
incremental strangler and a clean rewrite without fighting either.

It is not batteries-included. You bring your own ORM and validation, the
ecosystem is small, and some of the family packages move at different speeds. If
you want an opinionated end-to-end stack, that's a different tool.

But the primitives are the right primitives, and after 593 routes I never once
wanted to route around them.

Adopt: KickJS

Orinda Felix Ochieng — Sat, 18 Jul 2026 07:52:51 +0000

A field report from building — and stabilising — a large, multi-tenant
TypeScript backend on KickJS. No product internals here; just the framework,
the patterns it pushed us toward, and where it earned its keep.

Why write this

Most framework write-ups are written on day two, when the toy app compiles and
everything feels great. This one is written from the other end: after the
codebase grew into the hundreds of modules and thousands of routes, was
refactored repeatedly, and reached the boring, wonderful state where deploys are
uneventful. That is the only vantage point from which "should I adopt this?"
can be answered honestly.

Rounded, anonymised, the surface KickJS is carrying for us today:

Metric	Order of magnitude
Modules	~90
Controllers	~290
Use-cases (services)	~820
DI services total	~860
HTTP routes	~1,760
Plugins / adapters	~12

That is not a demo. It is a real system that a team ships to production on. It
is stable. That stability is the thesis of this article.

The mental model KickJS nudges you into

KickJS does not invent a new paradigm. It takes the decorator-driven,
dependency-injected server model that people already reach for in TypeScript and
makes the ergonomics of it good enough that you stop fighting it. The shape it
rewards is a clean three-layer slice:

HTTP  →  Controller  →  Use-case (@Service)  →  Reader / repository

Controllers stay thin. They validate input, call one use-case, shape the response. No business logic, no database.
Use-cases hold the behaviour. One responsibility each. Injected, testable in isolation.
Readers/repositories own the queries. Multi-source read logic lives here, away from the transport layer.

A representative controller — nothing exotic, and that is the point:

@ApiTags('Orders')
@Controller()
export class OrdersController {
  @Autowired() private readonly orders!: OrdersUseCase;

  @Post('/orders', { body: createOrderBody })
  async create(ctx: Ctx) {
    ctx.json(await this.orders.create(ctx.body), 201);
  }

  @Get('/orders', { query: listOrdersQuery })
  async list(ctx: Ctx) {
    ctx.json(await this.orders.list(ctx.query));
  }
}

@Controller() takes no path — the mount prefix comes from the module's route
declaration, so a controller is portable and the URL map lives in one place. The
DTO passed to @Post('/orders', { body: ... }) is the single source of truth
for validation and the generated types on ctx.body. You write the schema
once; the framework threads it everywhere.

The patterns that made it scale

1. Dependency injection that is actually pleasant

DI is easy to get wrong: too much magic and it becomes undebuggable; too little
and you hand-wire graphs forever. KickJS lands in the middle. @Autowired()
resolves by type, @Service() registers, and when you need an explicit handle
the token grammar is disciplined:

<scope>/<PascalKey>[/<suffix>]

Lowercase scope, PascalCase key. 'app/Users/repository',
'app/Cache/redis'. The convention is boring and therefore memorable, and it
scales to ~860 registered services without collapsing into a soup of ambiguous
providers. We have ~890 injection sites across the codebase and they read
the same everywhere.

2. Request-scoped providers as a first-class idea

The pattern that carried the multi-tenant design was request-scoped factories: a
provider whose lifetime is the request, resolved lazily, injected like anything
else. No ambient globals, no async-local-storage wrappers threaded by hand — the
per-request value is a dependency, so it participates in the same graph as
everything else and tests can substitute it trivially. If your system has any
notion of "the current X for this request," this alone is worth the price of
admission.

3. Context decorators with declared dependencies

This is the feature I did not know I wanted. Cross-cutting request work —
auth resolution, tenancy binding, entitlement gates, permission checks — is
expressed as context decorators that declare what they depend on and let the
framework order them:

const RequiresThing = defineHttpContextDecorator({
  key: 'thing_gate',
  dependsOn: ['actor', 'hostContext'],
  async resolve(ctx, deps, params) {
    // runs *after* 'actor' and 'hostContext' are populated
    return { thing: /* ... */ };
  },
});

dependsOn is the whole game. Instead of a fragile, hand-ordered middleware
chain where a reorder silently breaks a downstream assumption, each unit names
its prerequisites and the framework computes the order. We have ~15 of these
composed freely across the route surface, stacked several deep on a single
handler, and they just resolve in the right sequence. This is the cleanest
solution to the "middleware ordering hell" problem I have used.

4. Factory functions over base classes

Modules, adapters, and plugins are defined with factory functions —
defineModule({...}), defineAdapter({...}), definePlugin({...}) — not by
extending base classes or implementing marker interfaces. That sounds cosmetic.
It is not. Factory definitions compose, they are easy to type, they do not drag
in inheritance ceremony, and they give the tooling a stable shape to
auto-discover. A module entry file is small and declarative:

export const OrdersModule = defineModule({
  name: 'OrdersModule',
  build: () => ({
    routes() {
      return [{ path: '/orders', controller: OrdersController }];
    },
  }),
});

5. Compile-time codegen that catches real bugs

KickJS generates types for routes, services, and env from the source. Two things
make this exceptional rather than a gimmick:

It is a build step you actually run, so drift between your handlers and your typed route map is caught before runtime.
It enforces invariants. When two decorated classes would claim the same DI token, codegen stops and tells you exactly which two files collide and how to resolve it. When two handlers claim the same verb+path, it flags the duplicate. These are the classes of bug that normally ship silently and page you later; here they fail the build with a precise message.

I hit both during a framework upgrade. The output was not a stack trace — it was
a diagnosis with named files and three ranked remedies. That is the difference
between a tool that generates types and a tool that understands your project.

6. Errors that are already RFC 7807

Structured problem+json error responses are built in. You do not hand-roll an
error-class hierarchy and a serializer; you throw, and the global handler renders
a spec-compliant problem document with a stable code discriminator the client
can branch on. Every error surface in the system speaks the same shape for free.

7. Uniform pagination

List endpoints share one pagination contract — parse, clamp, and page through a
single helper rather than re-deriving limit/offset/filters per endpoint. We
use it in ~76 places and every list endpoint behaves identically from the
client's perspective. Consistency at that scale is not something you get by
discipline alone; you get it because the framework made the consistent path the
easy path.

8. Vite-powered HMR and auto-discovery

Development runs on Vite. Modules are auto-discovered, and hot-reload is
genuinely hot — edit a handler, the change is live, state survives. At this
module count, a dev loop that stayed fast is not a luxury; it is what kept
iteration velocity from collapsing under the weight of the codebase.

9. First-party Swagger, testing, and CLI adapters

OpenAPI docs, an integration-test harness, and a CLI generator ship as
first-party adapters that speak the same conventions as the core. Docs stay in
sync because they are derived from the same decorated source the router uses.
New surface is scaffolded by the generator, so it is born matching house style
instead of drifting from it.

10. A typed asset manager

(Proof: the official guide — https://kickjs.app/guide/asset-manager.html.)

Backends accumulate non-code files — email templates, PDF/HTML views, report
layouts — and the usual failure mode is a renderFile('./templates/foo.ejs')
string that survives static analysis and only explodes when the handler runs.
Worse, __dirname arithmetic breaks the moment you move to ESM, a monorepo, or a
bundled build. The asset manager kills all three problems. You declare namespaces
in kick.config.ts:

assetMap: {
  mails:   { src: 'src/templates/mails' },
  reports: { src: 'src/templates/reports', glob: '**/*.{ejs,html}' },
}

and reference files through a generated, type-checked accessor (the keys
strategy — 'auto' | 'strip' | 'with-extension' — decides whether the key
keeps its extension):

import { assets } from '@forinda/kickjs';
const path = assets.mails.welcome();            // strip
const path = assets.reports['receipt.ejs']();   // with-extension

There are four access patterns for different needs — the ambient assets proxy,
a useAssets() hook (handy for DI and testing), an @Asset('mails/welcome')
field decorator, and a resolveAsset(category, slug) resolver for dynamic
dispatch. The honest guarantee: kick typegen walks the assetMap and augments
the KickAssets interface, so the typed proxy gives you autocomplete and
catches property typos at compile time; a file that is genuinely missing on
disk surfaces at resolution as a structured UnknownAssetError carrying the
namespace and key. That is the right split — the framework can prove the name
you typed is one it knows, and it fails loudly and specifically when the file
itself is absent.

Dev-time, kick dev re-runs typegen on change and synthesises an in-memory
manifest by walking the directories, so new templates are usable immediately.
For production, kick build writes a .kickjs-assets.json manifest and the
resolver honours KICK_ASSETS_ROOT; kick build:assets refreshes just the
manifest without a JS rebuild. It is a small feature that quietly deletes an
entire category of runtime bug.

11. The CLI is a task runner — and a genuine plugin platform

kick is not just scaffolding — it is the project's command surface, and it
extends at two levels.

Level one, from config. Custom commands are declared declaratively and then
behave like first-party ones (they show up in kick --help, support sequential
steps and aliases):

commands: [
  { name: 'test',     description: 'Run tests',   steps: 'npx vitest run' },
  { name: 'ci:check', description: 'Typecheck + format check',
    steps: ['npx tsc --noEmit', 'npx prettier --check src/'],
    aliases: ['verify'] },
]

The payoff at scale is one entry point. Instead of a drift-prone spread of npm
scripts, a Makefile, and a shell folder, the team runs kick <thing> and the
config is the source of truth. New contributors discover the whole command
surface from kick --help.

Level two, a published contract. This is the part that makes it a platform
rather than a script bag. The extension contract lives in its own tiny,
dependency-free package — @forinda/kickjs-cli-kit (one commander peer) —
whose stated job is "the types and helpers a package implements to ship
kick-compatible commands, generators, and typegens without depending on the
full CLI." A plugin author imports the kit; app authors get the same helpers
re-exported from @forinda/kickjs-cli. (The split exists to break a dependency
cycle — the CLI already depends on its first-party plugins, so the contract is
hoisted into a package both sides import. That is a mature bit of architecture,
not an accident.)

The surface a plugin can contribute is broad:

import { defineCliPlugin, defineGenerator } from '@forinda/kickjs-cli-kit';

export const myPlugin = defineCliPlugin({
  name: 'my-org/tools',
  commands: [/* declarative shell commands */],
  register(program, ctx) {
    // full Commander access — ctx gives cwd, projectRoot, config, log
    program.command('hello <name>').action((n) => ctx.log(`hi ${n}`));
  },
  typegens: [/* your own codegen passes, run after the host's */],
  generators: [
    defineGenerator({
      name: 'widget',
      description: 'Scaffold a widget',
      args: [{ name: 'name', required: true }],
      files: (ctx) => [
        { path: `src/widgets/${ctx.kebab}.ts`,
          content: `export class ${ctx.pascal}Widget {}\n` },
      ],
    }),
  ],
});

Four extension points, all first-class: declarative commands, programmatic
Commander registration, your own typegens (custom codegen that runs after
the framework's pass), and kick g <name> generators. Generators even
support out-of-band discovery — a third-party package advertises
"kickjs": { "generators": "./dist/generators.js" } in its package.json and
its scaffolders appear under kick g exactly like the built-ins. The generator
context hands you every naming variant you need (pascal, kebab, camel,
snake, plural forms) plus a resolved projectRoot, so a scaffolder writes to
the right place regardless of which subdirectory the command was typed in. And
consistent with the rest of the framework, duplicate plugin/command/typegen/
generator ids throw a KickPluginConflictError — the same "fail loudly on
ambiguity" discipline the DI layer enforces.

The lesson: the CLI is built on the exact contract it exposes to you. Extending
it is not a plugin API bolted onto a closed tool — it is the same mechanism the
framework's own database tooling uses.

For completeness, the full set of typed extension factories the CLI exposes —
every one an identity helper that just gives you inference and forward-compat:

Factory	Extends	Shape
`defineConfig`	the whole `kick.config.ts`	the `KickConfig` contract that carries all of the below
`defineCliPlugin`	the CLI	`name` + any of `commands` / `register()` / `typegens` / `generators`
`defineGenerator`	`kick g <name>`	`{ name, description, args?, flags?, files(ctx) }` scaffolder
`defineTypegen`	codegen	`{ id, inputs, generate(ctx) }` — a custom typed-artifact pass
`defineDoctorExtension`	`kick doctor`	`{ checks: DoctorCheck[] }` merged after the built-ins
`defineDoctorCheck`	`kick doctor`	one `(ctx) => DoctorResult` health check

defineTypegen deserves a callout: an adopter plugin can emit its own typed
artifacts into .kickjs/types/ on the same watched pipeline the framework uses,
with a TypegenContext that hands you importTs() (load the adopter's schema at
generate time), writeFile(), a memoised getScanResult() (share the project's
AST walk instead of re-scanning), and a logger. That is how the database tooling
ships its schema types — and your team can ship theirs the same way. Config-level
extension points echo the same openness: modules.repo accepts a CustomRepoType
so you can register a repository backend the generators target, and every
duplicate id across plugins/commands/typegens/generators throws
KickPluginConflictError rather than silently last-wins.

12. Diagnostics: `doctor`, `explain`, `tinker`, `codemod`

The tooling story goes past build and run:

kick doctor — a pre-flight health check (Node version, required deps, decorator config, env wiring, typegen freshness). Run it on a fresh clone or in CI and it tells you what is wrong with the environment before you waste time debugging the app. Crucially it is extensible: adopters ship their own checks via doctor: { checks: [...] } in config (or the defineDoctorExtension / defineDoctorCheck helpers), each check receiving the same context the built-ins do and returning a pass/warn/fail with a fix hint. Your ORM-specific or secret-strength checks live in your config, and the core stays agnostic.
kick explain <error> — hands you a KickJS error and gets back a human explanation plus a suggested fix. The framework is self-documenting at the point of failure.
kick tinker — a REPL with the DI container and services already loaded. The Rails-console experience for a TypeScript backend: poke at a real service graph interactively.
kick codemod — AST-style rewrites for framework migrations, so version bumps that change conventions can be applied mechanically instead of by hand.

There is even an MCP server (kick mcp) so AI tooling can talk to the framework
on its own terms. The through-line: KickJS treats developer diagnostics as a
first-class part of the framework, not an afterthought.

13. Pluggable backends: swap an implementation without touching callers

This is the plugin/adapter system, and it is the pattern that kept the app's
edges clean. An adapter resolves a concrete backend at boot, validates its
config fail-fast, and registers it under a stable typed token. Everything
downstream injects the interface, never the implementation, and never
branches on environment.

The mailer is the canonical example. One adapter owns the decision:

export interface Mailer {
  readonly provider: string;
  send(message: OutboundEmail): Promise<SendResult>;
}
export const MAILER = createToken<Mailer>('app/Mailer');

export const MailAdapter = defineAdapter({
  // resolve provider from env, assert its secrets exist (crash boot if not),
  // register the concrete sender under MAILER
});

Consumers are trivial and provider-agnostic:

@Autowired(MAILER) private readonly mailer!: Mailer;
// ... this.mailer.send(msg) — no idea whether it's SMTP, an API, or a fake

Swapping the backend is a config change, not a code change: a dev runs a
console or fake mailer that logs to the app log or an in-memory store; CI
runs the fake and asserts on captured mail; production points at a real
provider. The call sites never move. We use the same shape for every external
dependency — object storage, queue, SMS, virus scanning, scheduling, payment
rails — each behind an adapter and a token. The result is that the core of the
app has no knowledge of any vendor, and any one of them can be replaced or
mocked without a ripple. Fail-fast config validation at boot is the other half:
a misconfigured production backend crashes startup with a named error, not the
first customer request.

Adapters and plugins are, again, factory-defined (defineAdapter({...}),
definePlugin({...})) and composed by name in their own aggregation files, so
adding or removing a backend is a local, declarative edit.

14. One validator, propagated everywhere

The single most leveraged decision in the codebase: request schemas are Zod, and
that one schema is the source of truth for both runtime validation and
the static types on the request context. You wire the validator once in config:

typegen: { schemaValidator: 'zod' }

Then a DTO written once:

export const createOrderBody = z.object({
  sku: z.uuid(),
  quantity: z.number().int().positive(),
});

attached to a route:

@Post('/orders', { body: createOrderBody })
async create(ctx: Ctx<KickRoutes.OrdersController['create']>) {
  // ctx.body is typed as { sku: string; quantity: number } AND already validated
}

does three jobs from one definition: it rejects bad input at the boundary with a
structured error, it makes ctx.body/ctx.query/ctx.params fully typed with
no manual interface, and it feeds the generated OpenAPI docs. Change the schema
and every one of those updates together — there is no second type to drift, no
validator to forget. Across the system this is used in hundreds of DTOs and
~186 typed-context handlers, and the reason list endpoints, bodies, and docs
all stay honest is that they are all downstream of the same object.

And the validator itself is a swap, not a lock-in: typegen.schemaValidator
takes 'zod' (default), 'kickjs-schema' — which infers through Zod, Valibot,
Yup, or any Standard Schema v1 adapter — or false to opt out entirely. You get
the single-source-of-truth ergonomics without being married to one schema
library. If you adopt KickJS for one reason, make it this one.

15. Bring your own database and ORM

KickJS has no persistence baked into the core. It is deliberately
ORM-agnostic — the framework's own tooling says so out loud (its doctor checks
carry the note that "the framework stays ORM-agnostic — Prisma / Drizzle /
Mongoose-specific checks belong in their respective adapters or in adopter
config, not in core"). Data access enters the same way every other backend does
here: behind an adapter and a token (see §13). The core knows about controllers,
DI, and routes; it does not know or care what is storing your rows.

Concretely, the persistence layer is a choice you configure, not a mandate:

modules: {
  dir: 'src/modules',
  repo: 'drizzle',   // or 'inmemory', 'postgres', … or a CustomRepoType
}

repo accepts a built-in string or a CustomRepoType you register, and the
generators scaffold against whatever you pick — kick g module order --repo postgres
generates a Postgres-shaped repository; the default inmemory gives you a
working module with zero database at all, which is superb for prototyping and
tests. If you have your own schema, defineTypegen's importTs() lets a plugin
read it at generate time and emit types for it, so even a bespoke data layer gets
first-class typed access.

For this system we made a specific, opinionated choice — Postgres with a typed
query layer — and it has served a large, multi-tenant workload well. But that is
our choice living in our adapters and config. Nothing in the framework forces
it. If your team wants Prisma, Mongoose, Kysely, raw SQL, or something exotic,
KickJS gets out of the way and lets you wire it the same clean way: an interface,
a token, an adapter that resolves the concrete backend at boot. You adopt the
framework without adopting its authors' database opinions.

Where it was genuinely exceptional

Refactor safety. The single most valuable property at scale. Renames,
module moves, and dependency reshuffles are backed by generated types and
codegen invariants, so large mechanical changes either compile and pass codegen
or fail loudly with a pointer to the exact problem. You refactor with the
confidence that the framework will not let a whole class of mistakes through.

Onboarding. Because every slice looks the same —
controller → use-case → reader, DI by convention, DTO-as-source-of-truth — a
new contributor learns one shape and can then read any of the ~90 modules.
The framework's opinions are the onboarding doc.

It gets out of the way. After the initial model clicks, you spend your time
on the problem, not on the framework. That is the highest compliment I can pay a
backend framework, and it is why the codebase reached "boring to deploy."

Sharp edges worth knowing (adopt with eyes open)

No honest adopt-report is all praise. None of these are dealbreakers; all are
worth knowing on day one:

Token uniqueness is enforced globally. Two classes with the same name in different modules will collide as DI tokens. This is a feature — it catches ambiguity — but it means your naming wants a domain prefix (OrdersInjuryService vs ClinicInjuryService) rather than bare, repeated names. Cheap to fix, better to know upfront.
Auto-discovery has rules. Module entry files and the glob that eager-loads your decorated classes must follow the framework's naming/registration conventions or things silently fall out of discovery (or degrade HMR to full restarts). The codegen advisories tell you when something is unregistered — read them.
Generated artifacts are part of the build. Treat codegen as a real step in CI and in your pre-push checks, not an afterthought. When it is wired into the gate, the invariants above protect you continuously.
A couple of doctor checks are shallow. In our setup kick doctor flagged tsconfig.json as missing even though a valid one — with both experimentalDecorators and emitDecoratorMetadata set — was present in the project root. Treat doctor as a fast smoke test of the environment, not a formal proof; when a check disagrees with reality, trust the build.

Every one of these is the framework being strict on your behalf. The strictness
is why the large system is stable.

Verdict

Adopt.

If you are choosing a TypeScript backend framework for something you expect to
grow — many modules, many routes, a team, a multi-year horizon — KickJS is a
well-thought-out choice. It does not dazzle you in a hello-world; it rewards you
at module two hundred. The decorator + DI + factory-module model is coherent,
the codegen catches the bugs that normally ship silently, the context-decorator
dependency model solves middleware ordering properly, and the whole thing stays
fast and refactorable at a scale where most stacks start to fray.

We built a large, real, multi-tenant system on it. It is in production. It is
stable. That sentence is the entire recommendation.

Learn more

Website / docs: https://kickjs.app/
Asset manager guide: https://kickjs.app/guide/asset-manager.html
Source (GitHub): https://github.com/forinda/kick-js

#KickJS #TypeScript #NodeJS #BackendFramework #DependencyInjection #DeveloperExperience #Zod #ORMagnostic #CLI #OpenSource #WebDev #SoftwareArchitecture

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.

DEV Community: Orinda Felix Ochieng

Route flags, context decorators and typed assets in KickJS: declare it once, use it everywhere

1. Route flags: facts about a route

2. Context decorators: typed values about a request

3. The asset manager: typed paths to your files

Configure

Generate types

Four ways to read an asset

In the build

4. How they fit together

5. Recipe: one "public" flag, every consumer

6. Recipe: the signed-in user, skipped on public routes

7. Recipe: plan-gated routes with a flag value and dependsOn

8. Recipe: per-route rate limits from one declaration

The three shapes a flag test can take

9. Recipe: flag or parameter? Choosing the right tool

10. Recipe: locale-aware emails from typed templates

11. Recipe: reports rendered per route

12. Recipe: flagging controllers you don't own

13. Type safety: what the compiler catches

14. Testing all three

Contributors, in isolation

Flags, without a request

The whole pipeline

Assets, with fixtures

15. Pitfalls

The CLI commands used

Recap

Links

Build a type-safe tasks API with KickJS and MongoDB, end to end

Table of contents

1. The type-safety map

2. Scaffold the project

3. A typed, validated environment

4. Mongoose models that type themselves

The task model

Users and categories

One function collects every model

5. A MongoDB adapter that puts models into DI

Generate it

Fill it in

Register the adapters

6. Authentication: passwords and tokens

Tokens

Passwords

Generate the module

The auth service

7. The current user as typed context

Generate it

Fill it in

8. Modules, DTOs and controllers

Generate the feature modules

DTOs: one Zod schema, three jobs

Controllers: typed handlers from generated types

9. Services: ownership in every query

10. Listing tasks: pagination, filters, sort and search

11. Categories

12. API docs for free

13. Run it and try it

14. Where to go next

The CLI commands used

Recap

Links

Realtime in KickJS: WebSockets, rooms, auth and scaling past one server

Table of contents

1. How the pieces fit

2. Install

3. Mount the WebSocket adapter

4. Your first gateway

5. The message format

6. Authenticating the handshake

6.1 Where does the token go?

6.2 Read and verify the token

6.3 Plug it into the adapter

7. Rooms: subscribing and checking access

7.1 Name rooms deliberately

7.2 Join personal rooms on connect

7.3 Subscribe — and check access every time

8. Publishing from HTTP routes and services

9. Put your own interface in front of the transport

`protect: true` — no overlapping runs

`try/catch` around every run

`shutdown()` stops every schedule

Pattern 1: fine to run everywhere — claim rows with `SKIP LOCKED`