nifra

# nifra

> nifra is a Bun-native, contract-first, framework-agnostic full-stack TypeScript framework. The HTTP core (`@nifrajs/core`) is a radix-routed, fully type-inferred server whose handler types flow to a never-throwing client (`@nifrajs/client`) with zero codegen - and graduate to a versionable contract without rewriting handlers. The whole lifecycle is `app.fetch(Request): Response`, so the same app runs on Bun, Node, Deno, and Cloudflare Workers. `@nifrajs/web` adds a framework-agnostic SSR layer (file routing, loaders/actions, streaming, SSG/ISR) with React, Solid, Vue, Svelte, and Preact adapters.

For an LLM implementing with nifra with no prior training data, read **[llms-full.txt](/llms-full.txt)** - it inlines every doc page, the package READMEs, and the complete export index in one file.

## Docs

- [Nifra - Getting started](/docs): Get started with Nifra: typed backend, agentic UI, bounded agent runs, full-stack SSR, and portable deployment.
- [Nifra vs. other frameworks - the honest comparison](/docs/comparison): How Nifra compares to the full-stack frameworks (Next.js, Nuxt, SvelteKit, React Router, TanStack Start) - and, as a standalone backend, to Hono and Elysia. Five UI frameworks, five runtimes, end-to-end types, partial prerendering, live refresh, and an agentic application layer built around typed capabilities.
- [Nifra - Routing](/docs/routing): File-based routing in Nifra: conventions, params, nested layouts.
- [Nifra - API & typed client](/docs/api): Build a typed JSON API with server()/defineContract + validate inputs with any Standard Schema, then consume it from a zero-codegen, never-throwing typed client.
- [Nifra - Loaders & actions](/docs/data): Typed loaders and actions in Nifra: data on the server, mutations, revalidation.
- [Nifra - Server functions](/docs/server-functions): Write a function on the server and call it from a component. The module never reaches the browser, the arguments are validated, and the mounted function is an ordinary route - so assurance, capabilities and the effect ledger all apply.
- [Nifra - Server components](/docs/server-components): Server-only views with schema-guarded props, owner-route authorization and native React, Vue, Svelte, Solid and Preact hydration.
- [Nifra - Optimistic UI & fetchers](/docs/mutations): Optimistic updates and concurrent fetchers in Nifra: instant feedback, row-level mutations.
- [Nifra - Rendering: SSR, streaming, SSG & ISR](/docs/rendering): Render critical HTML first, stream deferred data progressively, prerender static routes, and cache rendered pages with stale-while-revalidate - on every runtime including the edge.
- [Nifra - Hydration & pre-hydration forms](/docs/hydration): SSR pages become interactive after hydration. Nifra keeps that gap safe: progressive-enhancement forms and links work before it, and a JS-only form's broken native submit is guarded automatically.
- [Nifra - Islands: interactivity without hydration](/docs/islands): Add interactivity to a zero-runtime vanilla page with islands: an imperative DOM enhancer, or signals bound to server-rendered markup by name. No framework runtime, no hydration, and nifra check matches the markup against the code that mounts it.
- [Nifra - Streaming](/docs/streaming): Streaming SSR, Suspense, and defer() in Nifra - on every runtime including the edge.
- [Nifra - Query cache](/docs/query): Nifra's cross-framework keyed query cache: reactive queries, mutations, infinite lists, and SSR hydration.
- [Nifra - Frameworks](/docs/frameworks): One agnostic core, five UI frameworks: React, Solid, Vue, Preact, and Svelte - same loaders, streaming, islands, and routing, unchanged.
- [Nifra - Plugins & middleware](/docs/plugins): Extend Nifra with definePlugin (typed context, idempotent) + hook-bundle middleware. Official middleware: requestId, logger, etag, bearer, apiKey, basicAuth, jwt/jwks, csrf, ipRestriction, bodyLimit, cors, securityHeaders, rateLimit, compression, cacheControl, cache, prettyJson, timing, methodOverride, trailingSlash, language, poweredBy, combine, openapi, healthcheck, idempotency.
- [Nifra - security & hardening](/docs/security): Bounded request bodies, JSON prototype-poisoning defense, magic-byte file-upload validation, constant-time webhook verification, security response headers, and idempotency-key replay - the hardening primitives every production app needs, built in.
- [Nifra - Effect provenance](/docs/capabilities): A route declares the effects it performs, and `nifra check` fails it for being able to reach further than it declared. How reach is computed, why that shapes your modules, and how the declaration turns into an enforced policy.
- [Nifra - Auth & sessions](/docs/auth): Turnkey auth with @nifrajs/better-auth (OAuth, magic links, 2FA), or signed-cookie + server-store sessions, route guards, and CSRF with @nifrajs/auth.
- [Nifra - images](/docs/images): A CLS-safe responsive <Image> with pluggable loaders - a CDN, or Nifra's self-hosted resize endpoint (Bun.Image, sharp, or WASM on the edge) with optional signed URLs.
- [Nifra - i18n](/docs/i18n): One locale registry, locale-prefixed routing, negotiation and a tiny ICU message formatter on the platform Intl.
- [Nifra - Edge & bindings](/docs/edge): Typed platform bindings in Nifra: c.env, Platform<Env>, c.waitUntil, KV/D1 on the edge.
- [Nifra - WebSockets](/docs/websockets): app.ws(path, handler) registers a typed WebSocket route - an upgrade guard, a portable socket, contract-validated messages, and topic pub/sub - served on Bun, Deno, Node, and Cloudflare Workers.
- [Nifra - Deployment](/docs/deployment): One Nifra app, one command per target - Bun, Node (Docker), Deno Deploy, Cloudflare Pages, Vercel Edge or Node.
- [Nifra - CLI](/docs/cli): Every Nifra CLI command: dev, build and start, the check and contract gates, code generation, the agent and dev-server tools, and upgrades.
- [Nifra - Coding agents](/docs/agents): Nifra's agent layer: live MCP tools, bounded repairable turns, native approvals, resumable evidence, content-free browser views, capability registry, decision inbox, Run Studio, A2A, and AG-UI.
- [Nifra - Dev & HMR](/docs/dev): Use `nifra dev` for a Vite-backed state-preserving HMR loop, or `@nifrajs/web/dev` for a Bun-native HMR loop with no Vite dependency. Production builds use Bun.
- [Nifra - Troubleshooting](/docs/troubleshooting): Fixes keyed on the literal error strings Nifra prints: `may not ship to a browser` (backend code, a node: built-in or a server package reached a browser build), `resolveDispatcher` / `Invalid hook call` (duplicate React), and `@nifrajs/core is loaded 2 times` (duplicate core).
- [Nifra - Backends & API (dev and prod)](/docs/backends): How a Nifra backend reaches your app: inProcessClient feeds ctx.api to loaders, and createWebApp serves the backend over HTTP at the apiPrefix you set - in `nifra dev` and production alike, no hand-dispatch.
- [Nifra - Request budgets](/docs/budgets): Propagate one absolute deadline through Nifra requests and downstream adapters without resetting time at each hop.
- [Nifra - Execution causality](/docs/causality): Carry one bounded, payload-free lineage across the durable seams a trace cannot span: commands, events, workflows, projections, and repairs.
- [Nifra - Adapter certification](/docs/certification): Prove a storage, cache, job, runtime, or event adapter against its interface and emit a hash-verifiable capability matrix.
- [Nifra - Content & MDX](/docs/content): Typed content collections + MDX - author docs and blogs in Markdown with embedded components.
- [Nifra - Framework contract](/docs/contract): The one-page contract: LoaderContext shape, loader/action/meta/head signatures, the client↔server boundary, and the build-output contract - every signature verified against the source.
- [Nifra - Control APIs (one schema, every client)](/docs/control-api): Build an RPC-style control API on core routes: one schema per method gives request validation, a typed TypeScript client, and an OpenAPI 3.2 document whose SSE events let Swift, Kotlin, or Python clients be generated.
- [Nifra - Custom server (createWebApp)](/docs/custom-server): Run a page app from your own server entry with createWebApp: static and hashed files, a strict CSP on nifra's nonce, middleware order, loader error logging, graceful shutdown, and nifra check settings.
- [Nifra - Databases](/docs/database): Nifra is database-agnostic: use SQLite, Postgres, or any ORM (Drizzle, Prisma, Kysely) from your handlers and loaders, on Bun, Node, Deno, and the edge.
- [Nifra - Error codes](/docs/errors): Every error code Nifra recognises: what each one means and how to fix it. The dev overlay, nifra_explain and nifra_errors name these codes and link here.
- [Nifra - Failure laboratory](/docs/failure-lab): Replayable durable-failure schedules on virtual time: crash after commit, duplicate delivery, reordering, budget expiry, and checkpoint contention.
- [Nifra - Fonts](/docs/fonts): Self-host web fonts with zero layout shift: a build-time Google Fonts downloader (the next/font equivalent) plus CLS-safe @font-face + preload primitives.
- [Nifra - Frontend gotchas](/docs/frontend-guidance): Version-scoped React, Preact, Solid, Vue, Svelte, and Nifra frontend gotchas exposed through the CLI and MCP.
- [Nifra - Integrations (Stripe, and any npm library)](/docs/integrations): Third-party libraries work in Nifra as-is - handlers are plain TypeScript. The Stripe recipe end-to-end: SDK calls in a route, constant-time webhook verification, and idempotent processing.
- [Nifra - Keep-alive](/docs/keep-alive): Pages that stay mounted after the visitor leaves them: back and forward bring back the same page, with its scroll, form input and component state, and a sign-out drops them in every tab.
- [Nifra - Live refresh](/docs/live): Pages that stay fresh on their own: loaders declare live keys, a publish reloads only what read them, through the same authorized path a navigation takes.
- [Nifra 2.0 migration guide - upgrade from 1.x](/docs/migrate-2): Upgrade a Nifra 1.x application to 2.0: automated package and import moves, opt-in runtime plugins, client and web changes, external auth mounts, and release verification.
- [Nifra 3.0 migration guide - upgrade from 2.x](/docs/migrate-3): Upgrade a Nifra 2.x application to 3.0: automated dependency pins, the plain-data redirect return value, the frozen reserved typed-client segment keys and their codemod, the Node proxy transport default, and the release gates.
- [Nifra 5 upgrade guide - from 3.x, 4.x or an earlier 5.x](/docs/migrate-5): Upgrade a Nifra 3.x or 4.x application to 5.0: the chained upgrade command, the frontend/backend layout move and its follow-ups, drafted output schemas, the backend's HTTP mount, the 5.0 defaults that changed, and the release gates. Then move a 5.x app to 5.6.
- [Nifra - Migrating from Express, Hono, Fastify & Elysia](/docs/migrate-backend): Move a backend to Nifra: routing, middleware, validation, and body parsing map directly from Express, Hono, Fastify, and Elysia - and you gain a typed client, multi-runtime deploy, and optional SSR.
- [Nifra - Migrating from Next.js, Nuxt, SvelteKit & SolidStart](/docs/migrate-frontend): Move from a meta-framework to Nifra: file routes, data loading, API routes, layouts, and SSG/ISR map across React (Next), Vue (Nuxt), Svelte (SvelteKit), and Solid (SolidStart).
- [Nifra - Migrate route by route](/docs/migrate-route-by-route): Keep an existing Hono, Elysia, Express, or Workers app running while moving routes into typed Nifra handlers one at a time.
- [Nifra - Tracing & observability](/docs/observability): One trace from the request through the cache, the job queue and the worker, plus the OpenTelemetry SDK's own database and HTTP spans, without bundling the SDK.
- [Nifra - Partial prerendering](/docs/partial-prerendering): Serve a page's shared frame from a cached shell at once, then stream each per-visitor part as its own loader settles. Shared holes, server components in holes, a store shared by processes, Deno and Workers, eligibility rules, the no-JavaScript limit, proxies and connection limits.
- [Nifra - Runtime differences](/docs/runtime-differences): Where Bun, Node, Deno and Cloudflare Workers behave differently under the same Nifra app, with the fix and the Nifra option that decides it, exposed through the CLI and MCP.
- [Nifra security posture vs Hono, Fastify, Express, Elysia](/docs/security-comparison): A dimension-by-dimension security comparison of Nifra against the current releases of Hono, Fastify, Express, and Elysia - which hardening each framework ships by default, which is opt-in, and which is left to third-party packages.
- [Nifra - Security testing](/docs/security-testing): Security invariants, mutation testing, adversarial inputs, and runtime differential checks in Nifra.
- [Nifra - Project structure](/docs/structure): Where code lives in a Nifra app: routes/, frontend/, backend/, shared/ and public/, the route pair, and the import rules the build enforces so server code never reaches the browser.
- [Nifra - Contract-derived adversarial testing](/docs/testing): Turn route schemas into hostile input, response-conformance, replay, shrinking, and runtime-matrix tests with @nifrajs/testing.
- [Nifra - Types-first architecture](/docs/types-first): Nifra infers route types from path literals and handlers automatically, with optional Standard Schemas for validation, explicit contracts, OpenAPI, and agent-readable APIs.
- [Nifra - Verification ladder](/docs/verification): Five cumulative levels, from a typed contract to contract-derived invariant tests, that say what a Nifra project actually proves.
- [Nifra - WebMCP & predictive UI](/docs/webmcp): Expose explicit page-local WebMCP tools from typed Nifra capabilities while keeping remote MCP, authorization, receipts, and predictive UI reconciliation on one contract.

## Packages

- `@nifrajs/a2a` - Mount a nifra agent as an Agent2Agent (A2A) protocol server - the agent card on GET, the A2A 1.0 JSON-RPC binding on POST with SendMessage, streaming SendStreamingMessage over SSE, and GetTask projected from the runner's turn state. A protocol bridge over @nifrajs/agent; the model, state store, and approval transport stay injected per request.
- `@nifrajs/acp` - Agent Client Protocol backend for the Nifra agent protocol: drive Claude Code, Gemini CLI, Codex, or any ACP agent over stdio.
- `@nifrajs/ag-ui` - Mount a nifra agent as an AG-UI (Agent-User Interaction protocol) endpoint - one POST accepting RunAgentInput, a stream of AG-UI events out over SSE: run lifecycle, step and tool-call events from the runner's step evidence, text message events for the output, and a typed continuation for human-in-the-loop resume. A protocol bridge over @nifrajs/agent; the model, state store, and approval transport stay injected per request.
- `@nifrajs/agent` - Provider-neutral, typed, resumable agent turns built on Nifra tool contracts.
- `@nifrajs/agent-app` - Presentation-safe browser SDK for Nifra agent hosts: negotiated commands, ordered event streaming, and content-free view models over the agent protocol.
- `@nifrajs/agent-protocol` - Small backend-neutral session and event protocol for Nifra coding agents.
- `@nifrajs/agent-review` - A bounded, content-free review report contract for Nifra tooling.
- `@nifrajs/agent-telemetry` - Agent telemetry plugin - child spans for AI tool calls on /_nifra/tool/* and MCP endpoints.
- `@nifrajs/auth` - Session primitives for nifra - signed-cookie + server-store sessions, CSRF, and route guards. Bring your own identity (Better Auth / Lucia / OAuth); nifra owns the session.
- `@nifrajs/authjs` - Official Auth.js integration for nifra - mount Auth.js (OAuth, OIDC, credentials, WebAuthn-ready) into a nifra app, read sessions in handlers and loaders, guard routes, and drive it all from any frontend.
- `@nifrajs/aws-lambda` - AWS Lambda adapter for nifra - API Gateway HTTP API (payload v2) and Function URLs, buffered or streaming, with post-decode body limits and single-site header merging. Dependency-free.
- `@nifrajs/better-auth` - Mount better-auth into a nifra app - one app.use() wires /api/auth/*, plus typed getSession/requireSession guards. Structural typing: no hard dependency on better-auth.
- `@nifrajs/cache` - Typed KV cache for nifra - TTL, stale-while-revalidate, tag invalidation, and single-flight stampede protection on a pluggable store (in-memory default; bring CF KV / Redis). Dependency-free, runs on Bun/Node/Deno/Workers.
- `@nifrajs/cli` - The nifra CLI - zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).
- `@nifrajs/client` - Browser-safe, end-to-end-typed client for @nifrajs/core servers (Eden-style proxy).
- `@nifrajs/coding-agent` - Standalone, extensible Nifra coding-agent host and CLI.
- `@nifrajs/content` - Typed, schema-validated content collections for nifra - Markdown + frontmatter, framework-agnostic.
- `@nifrajs/core` - Bun-native, contract-first HTTP framework - the router, server, and route descriptor.
- `@nifrajs/cron` - Runtime-agnostic in-process cron for nifra - standard 5-field expressions + @macros, overlap-safe, error-isolated, graceful stop. For long-running servers (Bun/Node/Deno); Workers use the platform scheduled trigger. Dependency-free.
- `@nifrajs/deno` - Run a nifra app on Deno via Deno.serve - graceful stop(), opt-in signals and static files.
- `@nifrajs/devtools` - Interactive DevTools overlay for nifra dev - loader traces, ISR status, route metadata.
- `@nifrajs/edge` - Compact fetch-handler server for edge and serverless runtimes (Cloudflare Workers, Vercel Edge, Deno Deploy, Bun). Keeps the server().get().post() DX and the full request trust boundary - bounded body read, Content-Length pre-reject, prototype-pollution guard, JSON/urlencoded framing - in a fraction of the bundle.
- `@nifrajs/env` - Typed, validated environment variables for nifra - define a schema, get a frozen typed object, fail loud at boot listing every problem. Coercing helpers (number/port/boolean/url/enum) + any Standard Schema. Dependency-free, edge-safe.
- `@nifrajs/events` - Portable, versioned event contracts - a typed, transport-agnostic event envelope validated by any Standard Schema.
- `@nifrajs/graphql` - Mount a GraphQL endpoint on a nifra app - a spec-compliant GraphQL-over-HTTP handler you mount at POST /graphql, graphql-ws subscriptions over nifra's native WebSocket lane, and typed nifra context piped straight into your resolvers. Uses graphql's own execute/subscribe; no server framework re-bundled.
- `@nifrajs/i18n` - Framework-agnostic i18n for nifra - locale negotiation + a tiny ICU message formatter on the platform Intl. Dependency-free.
- `@nifrajs/image` - Image optimization for nifra - a CLS-safe responsive <Image> + pluggable loaders (CDN or self-hosted) + pure-JS dimension reading. Zero-dependency core; optional Bun.Image-backed resize endpoint at @nifrajs/image/server.
- `@nifrajs/island-trigger` - Tiny, framework-neutral island trigger scheduler for nifra.
- `@nifrajs/jobs` - Typed background jobs for nifra - enqueue work off the request path with retries, exponential backoff, and dead-lettering on a pluggable store. In-process worker for Bun/Node/Deno (Workers use CF Queues); the async companion to @nifrajs/cron. Dependency-free.
- `@nifrajs/mcp` - Build MCP servers - and MCP Apps (interactive `ui://` widgets, SEP-1865) - for a nifra app. The transport-agnostic JSON-RPC core (also used by `@nifrajs/cli`'s dev MCP), a Streamable-HTTP handler you mount at `POST /mcp`, and `defineMcpWidget`/`defineMcpTool` for tool results that render real UI in MCP hosts.
- `@nifrajs/mcp-db` - Serve a SQLite database as a fail-closed MCP server - allowlisted schema tools by default, opt-in read-only queries with plan verification.
- `@nifrajs/middleware` - Composable middleware for nifra - auth, CSRF, JWT/JWKS, IP restriction, CORS, body limits, response cache, timing, and operational helpers.
- `@nifrajs/mock` - Contract-based mock server - reads route schemas and generates fake responses.
- `@nifrajs/node` - Run a nifra app on Node's http server - a Request<->stream adapter with a graceful stop().
- `@nifrajs/otel` - Distributed tracing for nifra - W3C traceparent/tracestate propagation + OpenTelemetry-semantic-convention spans via a pluggable exporter. Bridge to the OpenTelemetry SDK or log spans directly; no SDK bundled. Edge-safe.
- `@nifrajs/pi` - Optional Pi coding-agent backend for the Nifra agent protocol.
- `@nifrajs/prompt` - Type-safe prompts - bind an instruction to input/output Standard Schemas and get validated, typed LLM results from any provider.
- `@nifrajs/proxy` - Reverse proxy for nifra - stream requests to one fixed upstream origin with hop-by-hop hygiene, SSRF-proof by construction. Dependency-free.
- `@nifrajs/runner` - Run requests through a nifra app's fetch and capture structured results - the engine behind the playground and the agent run/verify tool. Dependency-free; runs in the browser, Bun, Node, Deno, and on the edge.
- `@nifrajs/schema` - Built-in schema builder `t` - TypeBox-backed (free JSON Schema + compiled validators), implements Standard Schema so nifra routes validate it natively.
- `@nifrajs/skills` - Agent skills for nifra - portable SKILL.md bundles that teach a coding agent Nifra's contracts, boundaries, and CI gates, and point it at the live MCP server instead of stale recall.
- `@nifrajs/storage` - Blob storage mechanics for nifra - traversal-safe memory, filesystem, and R2 adapters, optional provider capabilities, and executable adapter conformance.
- `@nifrajs/testing` - Contract-derived adversarial tests, runtime-matrix response conformance, and cookie-aware in-process sessions for Nifra apps.
- `@nifrajs/ts-plugin` - TypeScript language-service plugin for nifra - go-to-definition from a route-path string literal to the routes/ file that serves it, and the frontend/backend zone rules as editor errors.
- `@nifrajs/uploads` - File-upload hardening for nifra - size + magic-byte type validation, short-TTL signed download URLs, and EXIF/metadata stripping. Edge-safe.
- `@nifrajs/web` - Framework-agnostic SSR core for nifra - the render seam + HTML document orchestration.
- `@nifrajs/web-preact` - Preact render adapter for @nifrajs/web - streaming SSR + hydration (no build plugin).
- `@nifrajs/web-react` - React render adapter for @nifrajs/web - SSR + hydration (Bun-native JSX, no Babel).
- `@nifrajs/web-solid` - Solid render adapter for @nifrajs/web - SSR + hydration, with the Solid Babel build plugin (@nifrajs/web-solid/plugin).
- `@nifrajs/web-svelte` - Svelte 5 render adapter for @nifrajs/web - SSR + hydration, with the .svelte compiler Bun plugin (@nifrajs/web-svelte/plugin).
- `@nifrajs/web-vanilla` - Zero-framework render adapter for @nifrajs/web - auto-escaping tagged-template HTML, ~0 KB client JS, interactivity via @nifrajs/web/islands.
- `@nifrajs/web-vue` - Vue render adapter for @nifrajs/web - streaming SSR + hydration, with a .vue SFC compiler Bun plugin (@nifrajs/web-vue/plugin).
- `@nifrajs/webmcp` - Typed WebMCP site tools and predictive UI contracts for Nifra.
- `@nifrajs/workers` - Cloudflare Workers helpers for nifra - a Durable Object hub for cross-connection WebSocket broadcast.
- `create-nifra` - Scaffold a new nifra app - `bun create nifra <dir>`.
- `nifra` - The nifra full-stack framework - unscoped meta-entry that re-exports @nifrajs/core, so `import { server } from "nifra"` works. Scaffold an app with `bun create nifra`; the rest of the framework lives under @nifrajs/*.