Cookbook
Receitas do mundo real que não cabem no quickstart. Cada receita resolve um problema comum com código pronto para copiar e colar que espelha os apps de exemplo executáveis — examples/hello (mínimo) e examples/shop (scoped transactions, filtragem de queries).
Receitas
| Receita | Problema que resolve |
|---|---|
| Autenticação e autorização | Identificar quem chama e expô-lo aos handlers via um scoped slot, e então autorizar rotas por role ou claim. |
| Acesso a banco de dados | Compartilhar um cliente de vida longa (db, cache, mailer) entre handlers via um singleton slot, e uma camada de serviço pura que você pode testar de forma unitária. |
| Erros e validação | Retornar respostas 4xx corretas e entender os envelopes automáticos 422 / 500 do Kata. |
| Logging | Correlacionar uma linha de log da camada de service com c.requestId passando um logger vinculado à requisição ao service como argumento. |
| Migrando do NestJS | Mapear cada bloco de construção do NestJS — controllers, providers, guards, pipes, DTOs — para seu equivalente funcional no Kata. |
| Non-goals e BYO | Veja o que o Kata deliberadamente deixa por sua conta — persistência, rate limiting, métricas, env, paginação — e o padrão idiomático bring-your-own para cada um. |
Como estas receitas são fundamentadas
Cada trecho é verificado contra a superfície real do framework, não parafraseado de memória:
- O core API exportado vive em
packages/kata/src/index.ts; os helpers de auth ficam sob@katajs-framework/core/jwt. - Apps de referência executáveis vivem em
examples/helloeexamples/shop.
Se uma receita mostra uma API, essa API existe hoje. Quando uma receita se apoia em algo planejado mas ainda não entregue, ela é rotulada como Planejado e linka para a issue de acompanhamento — nunca presuma que uma API planejada já funciona.
O context compartilhado
Cada receita se constrói sobre um arquivo. O Kata centraliza a injeção de dependência em uma única chamada defineContext({...}) (veja Context e DI e ADR-0004), e os helpers defineRoute / defineMiddleware / createApp que ela retorna são vinculados a esse context. A configuração idiomática os re-exporta para que o resto do app importe de ./context, nunca de @katajs-framework/core diretamente:
// 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 — uma instância para o processo inteiro (veja /pt/cookbook/database)
db: singleton(makeDb(process.env)),
// scoped slots — um valor por requisição, definido por um middleware (veja /pt/cookbook/auth)
currentUser: scoped<User>(),
})
// Vincula os helpers a este context, depois os importa em todos os outros lugares.
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) })Cada module passado para createApp é um arquivo *.route.ts importado com import * as; o Kata registra cada route que ele exporta. Veja App e createApp para a assinatura completa.
Convenções que toda receita segue
Estas são impostas em todo o projeto — os trechos as obedecem para que você possa colá-los:
- Apenas funcional — sem classes, sem decorators (ADR-0002).
- Apenas named exports — sem default exports.
- Sem
any— useunknownmais narrowing. - Schemas vivem em
<domain>.schema.ts, nunca inline numa route (ADR-0005). - Toda route declara schemas de
inputeoutput(ADR-0003). - DI passa por
c.get('key'), onde'key'precisa estar registrada emdefineContext(ADR-0004).
API planejada referenciada neste cookbook
Nenhuma receita depende hoje de API que exista só no roadmap — toda superfície mostrada já está publicada. A única superfície antes rastreada aqui, o middleware de nível de app (global) de primeira classe (#84, ADR-0012), foi entregue como a opção middlewares de createApp — veja Não-objetivos & BYO para como as receitas a usam.
Também entregues — documentadas como API disponível nestas receitas: o helper unificado
c.error+ envelope de erro (#18, ADR-0008), o error boundary global (#62), o modo de validação de output (#17, ADR-0009) e os schemas de output multi-status (#19, ADR-0011).
Leia a reference junto com as receitas
O cookbook é orientado a tarefas. Para a assinatura exaustiva de cada helper, veja a reference: defineContext, defineRoute, defineMiddleware, createApp, os middlewares embutidos e @katajs-framework/core/jwt.
Veja também
- O que é Kata e Por que Kata — a tese por trás das restrições.
- Layout do projeto — a estrutura travada
modules/<domain>/que toda receita pressupõe. - Cliente RPC — o cliente tipado
hc<AppType>que estes schemas alimentam de ponta a ponta.