nifra: Instructions file for Codex

AGENTS.md - Nifra quick reference for coding agents

Nifra is a Bun-native, multi-runtime, end-to-end-typed full-stack TS framework. This is the copy-paste cookbook so you don't have to read the source. Deeper docs live in docs/ and at /docs/contract. Machine surfaces for agents: nifra check --json (the done-gate), nifra context, and the MCP server (nifra mcp).

1 · Define a route (typed, chainable)

import { server } from "@nifrajs/core/server"

export const app = server()
  .get("/users/:id", (c) => ({ id: c.params.id })) // c.params typed from the path literal
  .get("/files/*path", (c) => ({ path: c.params.path })) // trailing wildcard

Return a value → serialized to JSON. Return a Response → used as-is.

2 · Validate a body/query at the trust boundary (auto-422)

import { t } from "@nifrajs/schema"

app.post(
  "/users",
  { body: t.object({ name: t.string({ minLength: 1 }), age: t.number() }) },
  (c) => ({ id: crypto.randomUUID(), name: c.body.name }), // c.body is typed + already validated
)

t.object rejects unknown fields by default (additionalProperties: false) → a structured 422 with { path: [...] } issues before the handler runs. Need to allow extras? t.looseObject. Query schema: { query: t.object({…}) } → c.query.

3 · Read platform env (KV / D1 / secrets)

// Type it ONCE on server<Env>() → c.env is typed everywhere below (no per-binding cast).
const app = server<{ MY_KV: KVNamespace; API_SECRET: string }>().get(
  "/x",
  (c) => c.env.API_SECRET, // c.env: Env  (it's `unknown` if you don't pass <Env>)
)

env is forwarded from app.fetch(request, { env }) (Workers bindings). Validate at the boundary.

4 · Set status / headers, and the control-flow rule

app.post("/things", { body: t.object({ name: t.string() }) }, (c) => {
  c.set.status = 201
  c.set.headers["x-created"] = "1"
  return { ok: true }
})

For full control, return a Response. Throw rule: throw new Response("", { status: 404 }) = an intentional HTTP response (control flow - bypasses _error); throw new Error(…) = the nearest _error boundary / a 500.