Coder Legion - Recent posts tagged kickjs

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

Tue, 22 Sep 2026 11:40:21 +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.

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

Tue, 22 Sep 2026 11:38:03 +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.