Skip to content

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 ​

RecipeProblem it solves
Authentication & authorizationIdentify the caller and expose them to handlers via a scoped slot, then authorize routes by role or claim.
Database accessShare a long-lived client (db, cache, mailer) across handlers via a singleton slot, and a pure-service layer you can unit-test.
Errors & validationReturn correct 4xx responses and understand Kata's automatic 422 / 500 envelopes.
LoggingCorrelate a service-layer log line with c.requestId by passing a request-bound logger into the service as an argument.
Migrating from NestJSMap every NestJS building block — controllers, providers, guards, pipes, DTOs — to its functional Kata equivalent.
Non-goals & BYOSee 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:

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:

ts
// 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
ts
// 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 — use unknown plus narrowing.
  • Schemas live in <domain>.schema.ts, never inline in a route (ADR-0005).
  • Every route declares input and output schemas (ADR-0003).
  • DI goes through c.get('key'), where 'key' must be registered in defineContext (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.error helper + 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 ​

Open-source — license TBD. Built on Hono + Zod.