Cookbook
Real-world recipes that don't fit in the quickstart. Each recipe solves one common problem with copy-pasteable code that mirrors the runnable example apps — examples/hello (minimal) and examples/shop (scoped transactions, query filtering).
Recipes
| Recipe | Problem it solves |
|---|---|
| Authentication & authorization | Identify the caller and expose them to handlers via a scoped slot, then authorize routes by role or claim. |
| Database access | Share a long-lived client (db, cache, mailer) across handlers via a singleton slot, and a pure-service layer you can unit-test. |
| Errors & validation | Return correct 4xx responses and understand Kata's automatic 422 / 500 envelopes. |
| Logging | Correlate a service-layer log line with c.requestId by passing a request-bound logger into the service as an argument. |
| Migrating from NestJS | Map every NestJS building block — controllers, providers, guards, pipes, DTOs — to its functional Kata equivalent. |
| Non-goals & BYO | See what Kata deliberately leaves to you — persistence, rate limiting, metrics, env, pagination — and the idiomatic bring-your-own pattern for each. |
How these recipes are grounded
Every snippet is checked against the actual framework surface, not paraphrased from memory:
- The exported core API lives in
packages/kata/src/index.ts; auth helpers under@katajs-framework/core/jwt. - Runnable reference apps live in
examples/helloandexamples/shop.
If a recipe shows an API, that API exists today. Where a recipe leans on something planned but not shipped, it is labelled Planned and links to the tracking issue — never assume planned API works yet.
The shared context
Every recipe builds on one file. Kata centralises dependency injection in a single defineContext({...}) call (see Context & DI and ADR-0004), and the defineRoute / defineMiddleware / createApp helpers it returns are bound to that context. The idiomatic setup re-exports them so the rest of the app imports from ./context, never from @katajs-framework/core directly:
// src/context.ts
import { defineContext, scoped, singleton } from '@katajs-framework/core'
import { makeDb } from './db'
import type { User } from './modules/users/users.schema'
export const k = defineContext({
// singletons — one instance for the whole process (see /cookbook/database)
db: singleton(makeDb(process.env)),
// scoped slots — one value per request, set by a middleware (see /cookbook/auth)
currentUser: scoped<User>(),
})
// Bind the helpers to this context, then import them everywhere else.
export const { defineRoute, defineMiddleware, createApp } = k
export type AppRegistry = typeof k.registry// src/main.ts
import { serve } from '@hono/node-server'
import { createApp } from './context'
import * as users from './modules/users/users.route'
const app = createApp({ modules: [users] })
serve({ fetch: app.fetch, port: Number(process.env.PORT ?? 3000) })Each module passed to createApp is a *.route.ts file imported with import * as; Kata registers every route it exports. See App & createApp for the full signature.
Conventions every recipe follows
These are enforced project-wide — the snippets obey them so you can paste them in:
- Functional only — no classes, no decorators (ADR-0002).
- Named exports only — no default exports.
- No
any— useunknownplus narrowing. - Schemas live in
<domain>.schema.ts, never inline in a route (ADR-0005). - Every route declares
inputandoutputschemas (ADR-0003). - DI goes through
c.get('key'), where'key'must be registered indefineContext(ADR-0004).
Planned API referenced in this cookbook
No recipe currently leans on roadmap-only API — every surface shown ships today. The one surface previously tracked here, first-class app-level (global) middleware (#84, ADR-0012), has since shipped as the middlewares option of createApp — see Non-goals & BYO for how the recipes use it.
Also shipped — documented as available API in these recipes: the unified
c.errorhelper + error envelope (#18, ADR-0008), the global error boundary (#62), output-validation mode (#17, ADR-0009), and multi-status output schemas (#19, ADR-0011).
Read the reference alongside the recipes
The cookbook is task-first. For the exhaustive signature of each helper, see the reference: defineContext, defineRoute, defineMiddleware, createApp, the built-in middleware, and @katajs-framework/core/jwt.
See also
- What is Kata and Why Kata — the thesis behind the constraints.
- Project layout — the locked
modules/<domain>/structure every recipe assumes. - RPC client — the typed
hc<AppType>client these schemas power end to end.