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 ·
Examples ·
Benchmarks ·
vs. other frameworks
nifra check catches a broken contract and an undeclared effect, and says how to fix both.
Nifra is a TypeScript framework for typed APIs and full-stack SSR. Define a route once and the client,
the validation, and the agent tools all follow from it. A coding agent gets a live, checkable view of
your project instead of stale docs.
Quick start
bun create nifra my-app
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
Typed end to end, no codegen
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
else result.error
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.
Work with your coding agent
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 @nifrajs/cli mcp
bun create nifra installs @nifrajs/cli as a dev dependency, so inside the project bunx nifra
runs the local copy:
bunx nifra init-agents
bunx nifra context
bunx nifra check
bunx nifra assure
bunx nifra levels
bunx nifra smoke
nifra smoke reads a fixture from nifra.smoke.ts (or --fixture <file>) that configures SSR; the
auth and hydration checks run only when the fixture supplies them. See the
CLI reference.
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.
Start from an example
The full list, with single-file examples, is in examples/.
What the web layer adds
- 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.
One contract. Every surface.
Nifra is for software that is built, operated, and used with agents in the loop. An agent 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.
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 }],
}),
reconcile: ({ previous, input, output }) => ({
state: { items: [...previous.state.items, input] },
version: output.cartVersion,
}),
})
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.
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.
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:
| Surface | Best for | Nifra's contract |
|---|
| WebMCP | An agent acting in the currently open page | Explicit tool allowlists, typed inputs/outputs, bounded receipts, deterministic prediction, versioned reconciliation |
| MCP / MCP Apps | Remote tools, background work, and rich tool results | The same core tool projected to remote MCP and ui:// widgets |
| AG-UI | Streaming an agent run into a product UI | SSE lifecycle, text/reasoning/tool deltas, shared-state snapshots/deltas, resumable evidence, typed resume |
| Agent App / Workbench | Browser and desktop control planes | Negotiated features, approvals, handoffs, decision inbox, capability registry, Run Studio |
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:
Proof, not promises
Agentic systems need more than “the model said it worked.” Nifra turns the important claims into gates:
bunx nifra check
bunx nifra assure
bunx nifra capabilities check
bunx nifra manifest diff
bunx 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.
Limits to know
- The local process and extension agent adapters contain crashes and accidents; they are not hostile-code sandboxes.
- 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.
Batteries (60 packages, all typed, all optional)
Package map 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
bun run build
bun run bench:http
Contributions welcome - see CONTRIBUTING.md. MIT licensed.