Nifra docs

[Nifra]

Nifra

The AI-native TypeScript framework.
Typed APIs and full-stack SSR on five UI libraries, one app across Bun, Node, Deno, and the edge -
built so both humans and coding agents can change it safely.

[npm] [downloads] [CI] [Bun >= 1.3] [MIT]

Documentation · Playground · Benchmarks · vs. other frameworks

Nifra is for software that is built, operated, and used with agents in the loop.

An agent should not be a chat bubble bolted onto an app, or a coding assistant guessing at an API. It should discover the real contract, call typed capabilities, stream progress into the UI, ask for approval at the right boundary, update state optimistically, reconcile with the server, and leave evidence that the work actually happened. Nifra makes that one system:

• Build surface: typed APIs, runtime schemas, a no-codegen client, full-stack SSR, and one app across five UI libraries and five runtimes.
• Agent surface: page-local WebMCP, remote MCP/MCP Apps, A2A, and AG-UI from the same capability and tool contracts.
• Execution surface: bounded agent turns, budgets, approvals, idempotency, cancellation, resumable evidence, and provider-neutral model ports.
• UI surface: deterministic predictive UI, shared run state, streamed deltas, human-in-the-loop decisions, content-free browser views, and Run Studio.
• Proof surface: live MCP project context plus typecheck, route assurance, effect provenance, manifests, and contract-derived verification gates.

One contract. Every surface.

The central design decision is simple: define the capability once, then project it to the surface that fits the moment. A page-local agent can use WebMCP while the page is open; a background agent can use remote MCP; another agent can use A2A; a human-facing client can consume AG-UI. They still meet the same typed validation, authorization, approval, output, and evidence boundary.

import { t } from "@nifrajs/schema"import { defineAgentCapability, registerWebMcpTools } from "@nifrajs/webmcp"
export const addToCart = defineAgentCapability({  name: "cart.add",  description: "Add a product to the current cart.",  input: t.object({ sku: t.string(), quantity: t.number() }),  output: t.object({ cartVersion: t.string() }),  writes: ["cart"],  execute: (input) => addItemOnTheServer(input),  predict: ({ input, version }) => ({    baseVersion: version,    patch: [{ op: "add", path: "/items/-", value: input }],  }),})
// Explicit page-local discovery. Unsupported hosts receive a safe no-op report.await registerWebMcpTools([addToCart])

The same addToCart.tool can be projected into Nifra's remote MCP adapter or called by an agent runner. Predictions are deterministic application code - not LLM guesses - and commit, rollback, conflict, expiry, and authoritative reconciliation are explicit outcomes.

See the WebMCP and predictive UI guide and the agent layer.

Start with a typed backend

bun create nifra my-app # scaffold the API startercd my-appbun installbun run dev

For a full-stack React app with SSR:

bun create nifra my-app --template site --framework react

Or add a backend to an existing project:

bun add @nifrajs/core @nifrajs/schema @nifrajs/client

import { server } from "@nifrajs/core/server"import { t } from "@nifrajs/schema"
export const app = server()  .get("/users/:id", (c) => ({ id: c.params.id }))  .post("/users", { body: t.object({ name: t.string() }) }, (c) => ({    id: crypto.randomUUID(),    name: c.body.name,  }))

The client is inferred from the server type - no codegen, no duplicated schema, no stale SDK:

import { client } from "@nifrajs/client"import type { app } from "./server"
const api = client<typeof app>("http://localhost:3000")const result = await api.users({ id: "42" }).get()
if (result.ok) result.data.id   // route return type, checked by tscelse result.error               // failures are returned, never thrown

Change a route and every caller stops compiling until it is updated. Add loaders, actions, streaming, defer()/<Await>, islands, query cache, progressive-enhancement forms, and server functions when the app grows. The same web layer runs on React, Vue, Solid, Svelte, or Preact.

The web layer also keeps pages fresh and fast without a second data layer:

• Live refresh - a loader names the keys it read with live(...); a publish reloads only those loaders on every open tab, through the same middleware, gates and loaders a navigation runs.
• Partial prerendering - the part of a page every visitor shares is served from a cache at once, and each per-visitor hole streams in as its loader settles.
• Server components on all five adapters - React RSC/Flight, and native server-rendered ranges for the others.
• Keep-alive - back and forward bring a page back with its state, scroll and focus.
• SSG and ISR with tag purges that clear data caches, the page store, live pages and the CDN in order, so a writer reads its own write.

Agentic backend: bounded, typed, observable

Nifra also provides the runtime for applications whose product is an agent. The model provider, credentials, durable state, tenancy, and policy are injected ports; the framework owns the safety and execution semantics around them.

import { createAgentState, runAgent } from "@nifrajs/agent"
const result = await runAgent(definition, { value: input }, ports, {  state: createAgentState("support-1"),  maxTurns: 8,})

You get typed tool contracts, bounded turns and budgets, approvals, cancellation, idempotency, resumable token-only evidence, model/token streaming, transient shared state, and composable telemetry. A failed post-turn gate can become a bounded repair turn in the standalone nifra-agent host. The local process and extension adapters contain crashes and accidents; they are not hostile-code sandboxes.

Agentic UI: from intent to visible state

The UI is not an afterthought. Nifra gives an agent several deliberate ways to interact with an app:

For a predictive interaction, the application supplies a pure patch and a reconciliation rule. The store applies it atomically, then either accepts authoritative server state or reports rollback, conflict, or expiry. The human UI remains fully functional when no agent host is present.

Interoperate without rewriting the agent

The runner is the center; protocol adapters are edges:

• @nifrajs/mcp exposes tools and MCP Apps.
• @nifrajs/webmcp exposes explicit page-local tools and predictive UI.
• @nifrajs/a2a mounts an A2A 1.0 card plus JSON-RPC/SSE.
• @nifrajs/ag-ui mounts AG-UI events over SSE.
• @nifrajs/agent-app provides a backend-neutral browser client.
• @nifrajs/coding-agent, @nifrajs/agent-protocol, and @nifrajs/pi provide a standalone coding-agent host; @nifrajs/acp drives any Agent Client Protocol agent through it.

Every protocol boundary still needs application authentication and authorization. Public reference adapters keep credentials, durable storage, tenant state, and operated policy outside the package so you can supply the right implementation for your deployment.

Give coding agents a live project, not stale docs

Register Nifra once and an agent can inspect the actual project, fetch version-checked examples and types, scaffold in the correct route directory, run HTTP/SSR/WebSocket checks, inspect recent requests, and loop on structured fixes:

claude mcp add nifra -- bunx nifra mcpnifra init-agents
nifra context       # live route and convention mapnifra smoke         # real SSR, API, auth and hydration requests against the buildnifra check         # typecheck, drift, and bundle-boundary gatenifra assure        # route security evidence gatenifra levels        # cumulative proof level and next missing rung

The local server runs where your code lives - your source never reaches Nifra. The teaching tools are also hosted at mcp.nifra.dev for agents that only need the verified Nifra corpus. Skills are available for Pi and Claude Code.

Proof, not promises

Agentic systems need more than “the model said it worked.” Nifra turns the important claims into gates:

nifra checknifra assurenifra capabilities checknifra manifest diffnifra levels --min 1

• nifra check catches type drift, raw calls around the typed client, server-only bundle leaks, and other contract violations.
• nifra assure classifies the live route graph and fails when required authentication, validation, rate limiting, CSRF, or body-cap evidence is missing.
• nifra capabilities check compares declared effect tokens with the module graph and a reviewed lockfile.
• nifra manifest diff detects contract, assurance, effect, and response-sensitivity changes at promotion time.
• nifra levels reports the highest cumulative proof level a project actually holds, from typed contract to contract-derived invariant tests.

Docs and examples are compiled against the live API, and the machine-readable MCP corpus is generated from built packages. An agent gets a repairable diagnostic instead of a stale suggestion.

Full-stack portability, without the framework tax

The app lifecycle is app.fetch(Request): Promise<Response>. Define it once and deploy to Bun, Node, Deno, Cloudflare Workers/Pages, or Vercel Edge with a small adapter. The web layer supports React, Vue, Solid, Svelte, and Preact without changing the route/data model.

The published snapshot in site/shared/data/benchmarks.json is the source of truth for the website tables and benchmark comparison articles. The benchmark suites merge fresh results into it through bench/site-bench.ts. The public tables include rows where Nifra loses and keep bare HTTP, middleware-shaped HTTP, dynamic SSR, and cacheable SSR results separate.

See benchmark methodology and full results, and run bun run bench:http / bun run bench:ssr yourself.

Batteries (56 packages, all typed, all optional)

The package map is organized by job:

All packages are optional and typed. Start with the core, then add only the surfaces your product needs. Browse the complete documentation.

Develop

bun installbun run check          # lint, typecheck, tests, docs, corpus, and size gatesbun run build          # emit dist/ for all packagesbun run bench:http     # reproducible HTTP matrix

Contributions welcome - see CONTRIBUTING.md. MIT licensed.