Quickstart
This builds a fully-typed /users API — create a user, fetch one back, watch a validation failure, and hit a JWT-protected /me route — in nine small files. It is exactly examples/hello.
The plan: read the nine files top to bottom (each one introduces one Kata idea, and never references a file you haven't seen yet), boot the app, then call it with curl and watch every contract hold. Each step links out to the concept guide that covers it in depth, so you can skim here and dig in later.
Install
Kata has two peer dependencies — Hono (the HTTP base) and Zod (schemas) — plus Hono's Node adapter to boot a server on Node.
npm install @katajs-framework/core hono zod @hono/node-server
# or: pnpm add @katajs-framework/core hono zod @hono/node-serverPackage name vs. command
The framework is Kata, but its npm package is @katajs-framework/core — the bare kata name on npm belongs to an unrelated, dormant package. So you install and import @katajs-framework/core (import … from '@katajs-framework/core'), while the CLI keeps the short kata command (kata init, kata verify). npx @katajs-framework/core … also works, as an alias — but pnpm dlx needs --package=@katajs-framework/core kata …, because the package ships two bin names and pnpm will not pick between them.
Run the worked example from source
The finished app this page builds also lives in the repo, so you can skip the typing and run it directly:
git clone https://github.com/VicenzoMF/kata.git
cd kata && pnpm install
pnpm --filter=hello dev # boots examples/hello on http://localhost:3000The nine files
Kata locks the folder layout so every route, service, schema, and test is findable by glob (see project layout). The example folds app.ts into main.ts, and adds a small config.ts plus a second module (auth) for token minting, leaving nine files:
examples/hello/src/
├── context.ts # defineContext({ ... })
├── config.ts # JWT_SECRET, TOKEN_TTL_SECONDS
├── middlewares/
│ └── auth.ts # jwtAuth → fills the currentUser slot
├── modules/
│ ├── users/
│ │ ├── users.schema.ts # Zod DTOs
│ │ ├── users.service.ts # pure functions
│ │ └── users.route.ts # defineRoute calls only
│ └── auth/
│ ├── auth.schema.ts # token request/response DTOs
│ └── auth.route.ts # POST /auth/token
└── main.ts # createApp + serveBelow, the files appear in dependency order — each one only ever imports from a file you've already seen.
1. Schemas (DTOs) — modules/users/users.schema.ts
Every domain's Zod schemas live in <domain>.schema.ts, never inline in the route. Export the z.infer types alongside them, so a single import pulls both the runtime schema and the compile-time type. This is the first file because context.ts, next, needs the User type it exports.
import { z } from 'zod'
export const UserSchema = z.object({
id: z.string(),
name: z.string(),
email: z.string().email(),
})
export const UserClaimsSchema = z.object({
sub: z.string().min(1),
name: z.string().min(1),
email: z.string().email(),
})
export const CreateUserBodySchema = z.object({
name: z.string().min(1),
email: z.string().email(),
})
export const GetUserParamsSchema = z.object({
id: z.string(),
})
export type User = z.infer<typeof UserSchema>
export type UserClaims = z.infer<typeof UserClaimsSchema>
export type CreateUserBody = z.infer<typeof CreateUserBodySchema>2. Declare every dependency once — context.ts
defineContext is the single place dependencies are registered. There are two kinds of slot:
singleton(value)— lives for the process lifetime (db pool, logger, mailer).scoped<T>()— one value per request, filled by a middleware (current user, tenant id, request id).
defineContext returns defineRoute, defineMiddleware, and createApp already bound to your registry. Re-export them so the rest of the app inherits the types — c.get('key') only type-checks for keys you registered here. The currentUser slot below is typed against the User DTO from the schema file you just saw, not unknown.
import { defineContext, scoped, singleton } from '@katajs-framework/core'
import type { User } from './modules/users/users.schema'
type Logger = { info: (msg: string, extra?: object) => void }
const logger: Logger = {
info: (msg, extra) => console.log(`[hello] ${msg}`, extra ?? ''),
}
export const k = defineContext({
logger: singleton(logger),
currentUser: scoped<User>(),
})
export const { defineRoute, defineMiddleware, createApp } = k
export type AppRegistry = typeof k.registrySee context & DI for the full slot model.
3. Business logic — modules/users/users.service.ts
Services are plain, pure functions — trivial to unit-test, no framework imports. The in-memory Map here stands in for a real store.
import type { CreateUserBody, User } from './users.schema'
const store = new Map<string, User>()
export async function getUser(id: string): Promise<User | null> {
return store.get(id) ?? null
}
export async function createUser(input: CreateUserBody): Promise<User> {
const id = crypto.randomUUID()
const user: User = { id, ...input }
store.set(id, user)
return user
}More on the boundary in services.
4. Shared config — config.ts
A small config.ts at the src/ root (a spot the layout leaves open) holds the one secret the JWT flow needs. The auth middleware next, and the token-minting route later in this walkthrough, both import it — they must agree, or every token fails verification:
// src/config.ts
export const JWT_SECRET = process.env['JWT_SECRET'] ?? 'dev-secret'
export const TOKEN_TTL_SECONDS = 60 * 60WARNING
dev-secret keeps the example zero-config. A real app sets JWT_SECRET from the environment and refuses to boot in production when it is unset. Never ship dev-secret.
5. Middleware & scoped slots — middlewares/auth.ts
A middleware declares which scoped slots it provides; its handler fills them. Returning a Response short-circuits the request before the handler runs.
Kata ships JWT auth under @katajs-framework/core/jwt. jwtAuth reads an Authorization: Bearer token, verifies the signature and time claims, parses the payload with your Zod schema, and fills the slot. The resolve() hook maps the validated claims onto the app's User. Keep the defineMiddleware wrapper so the provides literal stays greppable and lint-checkable.
import { jwtAuth } from '@katajs-framework/core/jwt'
import { JWT_SECRET } from '../config'
import { defineMiddleware } from '../context'
import { type User, UserClaimsSchema } from '../modules/users/users.schema'
export const requireUser = defineMiddleware({
provides: ['currentUser'] as const,
handler: jwtAuth({
secret: JWT_SECRET,
claims: UserClaimsSchema,
resolve: (claims): User => ({ id: claims.sub, name: claims.name, email: claims.email }),
}),
})To fill a slot with c.set directly, or to layer authorization with requireRole / guard, see middleware and the auth cookbook.
6. Routes — modules/users/users.route.ts
Every route declares mandatory input and output schemas — omitting either is a TypeScript error. Inside the handler, c.input is fully typed from the input schemas. A handler may either return a value (validated against output, then serialized) or return c.json(...) / c.error(...) to set a custom status.
output may be a single schema (the 200 body) or a status→schema map — { 200: UserSchema, 404: ErrorBodySchema } — that types and validates each status. ErrorBodySchema is Kata's unified error envelope, the canonical thing to put behind a 4xx/5xx status. Routes that read a scoped slot list the providing middleware in use: — meRoute below lists the requireUser middleware from the previous file.
import { ErrorBodySchema } from '@katajs-framework/core'
import { defineRoute } from '../../context'
import { requireUser } from '../../middlewares/auth'
import { CreateUserBodySchema, GetUserParamsSchema, UserSchema } from './users.schema'
import { createUser, getUser } from './users.service'
export const getUserRoute = defineRoute({
method: 'GET',
path: '/users/:id',
input: { params: GetUserParamsSchema },
output: { 200: UserSchema, 404: ErrorBodySchema },
handler: async (c) => {
const user = await getUser(c.input.params.id)
if (!user) return c.error('not_found', 'User not found', { status: 404 })
return user
},
})
export const createUserRoute = defineRoute({
method: 'POST',
path: '/users',
input: { body: CreateUserBodySchema },
output: UserSchema,
handler: async (c) => createUser(c.input.body),
})
export const meRoute = defineRoute({
method: 'GET',
path: '/me',
use: [requireUser],
input: {},
output: UserSchema,
handler: async (c) => c.get('currentUser'),
})c.get('currentUser') in meRoute type-checks only because requireUser provides that slot and is listed in use:. Full reference in routes & schemas.
7. Token DTOs — modules/auth/auth.schema.ts
The token-minting route below needs its own DTOs — same rule as users.schema.ts: schemas live in <domain>.schema.ts, never inline in the route.
import { z } from 'zod'
export const TokenRequestSchema = z.object({
id: z.string().min(1),
name: z.string().min(1),
email: z.string().email(),
})
export const TokenResponseSchema = z.object({
token: z.string(),
})
export type TokenRequest = z.infer<typeof TokenRequestSchema>
export type TokenResponse = z.infer<typeof TokenResponseSchema>8. Mint a token — modules/auth/auth.route.ts
This route signs a JWT with signJwt so you can exercise /me without external tooling. It trusts its caller and is not how you authenticate real users:
import { signJwt } from '@katajs-framework/core/jwt'
import { JWT_SECRET, TOKEN_TTL_SECONDS } from '../../config'
import { defineRoute } from '../../context'
import { TokenRequestSchema, TokenResponseSchema } from './auth.schema'
export const mintTokenRoute = defineRoute({
method: 'POST',
path: '/auth/token',
input: { body: TokenRequestSchema },
output: TokenResponseSchema,
handler: async (c) => {
const { id, name, email } = c.input.body
const token = await signJwt(
{ name, email },
{ secret: JWT_SECRET, subject: id, expiresInSeconds: TOKEN_TTL_SECONDS },
)
return { token }
},
})The real seam for login, password hashing, and refresh is yours — see the JWT guide and auth cookbook.
9. Boot it — main.ts
createApp({ modules }) wires every exported route in each module into a Hono app. A module is just the namespace import of a .route.ts file — both users.route.ts and auth.route.ts from the last few steps. Hand app.fetch to @hono/node-server to listen.
Cross-cutting middleware goes in the optional middlewares slot — a chain that runs before every route's own use:. The first-party hardening built-ins (cors(), secureHeaders(), bodyLimit()) are the canonical case: declare them once and every route is covered.
import { serve } from '@hono/node-server'
import { bodyLimit, cors, secureHeaders } from '@katajs-framework/core'
import { createApp, k } from './context'
import * as auth from './modules/auth/auth.route'
import * as users from './modules/users/users.route'
const app = createApp({
modules: [users, auth],
middlewares: [cors(), secureHeaders(), bodyLimit({ maxSize: 8 * 1024 })],
})
const port = Number(process.env['PORT'] ?? 3000)
serve({ fetch: app.fetch, port }, (info) => {
k.resolve('logger').info(`listening on http://localhost:${info.port}`)
})TIP
The example also passes requestLogging: true and an explicit outputValidation knob. Both are optional. See app middleware and lifecycle.
Run it
From the cloned repo, the example is wired with tsx:
pnpm --filter=hello dev # tsx watch src/main.ts → http://localhost:3000In a standalone project, add tsx (npm i -D tsx) and run tsx watch src/main.ts.
Call it
Create a user, then fetch it back:
# Create a user (valid body) → 200, validated against UserSchema
curl -s localhost:3000/users \
-H 'content-type: application/json' \
-d '{"name":"Ada","email":"ada@example.com"}'
# {"id":"f81d4fae-…","name":"Ada","email":"ada@example.com"}
# Fetch it back by id → 200
curl -s localhost:3000/users/f81d4fae-…
# Unknown id → 404, the unified error envelope from c.error
curl -s localhost:3000/users/none
# {"error":"not_found","message":"User not found"}Validation fails before your handler
Kata validates input before the handler runs. On failure it responds 422 with a normalised envelope: error: "validation_failed" plus issues keyed by the input section that failed (params, query, body, or headers).
curl -s localhost:3000/users \
-H 'content-type: application/json' \
-d '{"name":"","email":"not-an-email"}'{
"error": "validation_failed",
"issues": {
"body": [
{ "path": "name", "code": "too_small", "message": "String must contain at least 1 character(s)" },
{ "path": "email", "code": "invalid_string", "message": "Invalid email" }
]
}
}Each field issue is { path, message, code }, with optional expected / received for type mismatches. Output is validated too, after the handler returns: a value that does not match its output schema yields 500 {"error":"internal_output_shape_mismatch"} and is logged server-side — the wrong shape never reaches the client. Full treatment in errors.
The JWT-protected /me flow
Mint a token, then call /me with it:
# Mint a token for an identity (stand-in for a real login)
curl -s localhost:3000/auth/token \
-H 'content-type: application/json' \
-d '{"id":"42","name":"Ada","email":"ada@example.com"}'
# {"token":"eyJhbGc…"}
# No token → 401, the unified envelope
curl -s localhost:3000/me
# {"error":"unauthorized","message":"Missing bearer token"}
# With the token → 200, the resolved currentUser
curl -s localhost:3000/me -H 'Authorization: Bearer eyJhbGc…'
# {"id":"42","name":"Ada","email":"ada@example.com"}requireUser verifies the token, parses the claims with UserClaimsSchema, and resolve() reshapes them into the currentUser slot that meRoute reads.
Where to next
- Context & DI — singletons, scoped slots, and the registry.
- Routes & schemas — input/output contracts in depth.
- Middleware and app middleware — slot-filling and the global chain.
- Errors — the 422/500 envelopes and
c.error. - JWT — real auth, guards, and the
resolve()hook. - RPC client —
hc<AppType>for end-to-end typed calls, no codegen. - Project layout — the locked folder structure.