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.

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 starter
cd my-app
bun install
bun 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 tsc
else 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.

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 mcp
nifra init-agents

nifra context       # live route and convention map
nifra run           # real request through the current app
nifra check         # typecheck, drift, and bundle-boundary gate
nifra assure        # route security evidence gate
nifra 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 check
nifra assure
nifra capabilities check
nifra manifest diff
nifra 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 (57 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 install
bun run check          # lint, typecheck, tests, and coverage
bun run build          # emit dist/ for all packages
bun run bench:http     # reproducible HTTP matrix

Contributions welcome—see CONTRIBUTING.md. MIT licensed.