CLI
nifra runs, builds, checks and upgrades an app from its project root. It reads routes/, backend/framework.ts, backend/app.ts and nifra.config.ts and wires the right @nifrajs/web entrypoint, so there is no dev.ts, build.ts or server.ts to write. create-nifra scaffolds the layout.
nifra dev # true-HMR dev server (Bun native HMR + Nifra SSR) - http://localhost:4321
nifra dev --vite # the Vite middleware pipeline instead (automatic when vitePlugins are your ONLY transforms)
nifra build # full Bun deploy → dist/server.js + content-hashed dist/assets/ (default target: bun)
nifra start # run dist/server.js on Bun
nifra build --target cloudflare # also: node | deno | vercel | static; configure custom adapters in nifra.config.ts first
# dev + start share the default port 4321. Override per run: --port <n> (alias -p) or the PORT env var.
# flags: --port <n> (dev/start) · --out <dir> (build/start) · --target <t> (build) · --poll (dev)
# --vite | --bun (dev/build) force the pipelineThe layout the CLI reads
nifra dev runs the Bun-native HMR dev server; nifra build runs the production build (content-hashed client assets plus a target-specific server); nifra start runs the default Bun output. The generated server serves assets and SSR with matched-route chunks preloaded and route CSS linked in each <head>.
One rule picks the bundler, and it is the same rule in both phases - so a project can never be bundled by one toolchain in dev and the other in production. Bun runs everything, except an app whose only transforms are vitePlugins: the Bun pipeline cannot run those, so that app gets Vite for dev and build alike, and says so. --vite / --bun force the choice; --bun is refused on a Vite-only app rather than dropping its transforms silently. Every dev and build run prints which bundler it picked and why, and nifra check answers the same question without starting a server - see which pipeline runs, when for the full table.
my-app/
routes/ # the URL tree: index.tsx, _layout.tsx, [id].tsx, each with an optional x.backend.ts half
backend/
framework.ts # the render adapter and server options - deploy-safe
app.ts # export const backend = server()... (optional - the typed API)
frontend/ # components and browser code
shared/ # schemas, types and helpers both sides import
nifra.config.ts # CLI-only: client module, deploy target, dev/build pluginsThese paths are fixed: the CLI resolves them from the project root. backend/app.ts is optional; without it nifra dev and nifra build run the pages alone. A root backend.ts or framework.ts, the layout before 4.0, is refused with the command that moves it, and nifra check reports it as NF-C038: run nifra migrate layout. Only the entry file is pinned; the feature modules it .merge()s can live anywhere under backend/. Keep backend/app.ts a composition root - merging modules, registering no routes of its own - so each route's capability reach stays its own module's. What goes in each zone, and what the builds refuse to cross, is on Project structure.
backend/framework.ts and nifra.config.ts
Keep the render adapter and the server options (apiPrefix, mounts, csp, i18n) in deploy-safe backend/framework.ts: the generated server entry imports it. Put clientModule, the deploy target, Vite plugins, compiler plugins, conditions, and defines in CLI-only nifra.config.ts, which re-exports the adapter. This keeps build tooling and native dependencies out of generated server bundles.
// backend/framework.ts - deploy-safe; the generated server entry imports this file.
import { reactAdapter } from "@nifrajs/web-react"
export const adapter = reactAdapter
export const apiPrefix = "" // "" keeps backend/app.ts loader-only; "/api" also serves it over HTTP
// nifra.config.ts - CLI-only build/dev tooling; never imported by a deployed server.
// doc-check: skip - needs the third-party @vitejs/plugin-react; install it to run this.
import react from "@vitejs/plugin-react"
export { adapter } from "./backend/framework"
export const clientModule = "@nifrajs/web-react/client"
export const target = "bun" // what nifra build emits; nifra target <t> switches it
export const vitePlugins = [react()] // only if you want Vite's dev pipeline
// Vue/Svelte/Solid also export:
// clientPlugins = [vueBunPlugin("dom")] // compile routes for the client build
// serverPlugins = [vueBunPlugin("ssr")] // compile routes into the target's server bundle
// conditions = ["solid"] // Solid: resolve solid-js to its source
// define = { __VUE_OPTIONS_API__: "true", ... } // Vue feature flagsOrdinary vercel builds default to Edge. To opt into Node.js 22, export both target = "vercel" and vercelRuntime = "node" from nifra.config.ts, then run nifra build (or nifra build --target vercel) and vercel deploy --prebuilt from the project root. Both Bun and Vite builds write .vercel/output unless --out overrides it. Omit the selector or use "edge" to retain Edge; other values and use with a different target are refused before output is cleared. There is no separate runtime flag. Node functions support Node built-ins but not Bun APIs or a persistent server; the CLI/build still requires Bun. See runtime output and limitations.
Command reference
Every command nifra --help lists, by what it is for. Most take --json for agents and CI. --env-file <path> works on every command and may repeat (a later file wins; a variable already set in the environment is never overwritten), which matters because commands that reflect your app import it. A dry run is the default wherever a command edits files.
Run and build
Develop, build a deploy directory, and run it. Started from a global or linked install, nifra dev, build, start and check run through the project's own @nifrajs/cli, so the app loads one @nifrajs/core; NIFRA_LOCAL_CLI=0 runs the CLI as invoked.
| Command | What it does |
|---|---|
nifra dev [--port <n>] [--vite | --bun] [--poll] | The dev server with true HMR, on port 4321. Bun runs it unless vitePlugins are the app's only transforms. --no-indicator hides the in-page issues badge. |
nifra build [--target <t>] [--out <dir>] [--transport <module>] [--prerender <paths>] [--report] | A complete deploy directory for bun, node, deno, cloudflare, vercel or static. The server entry is generated from backend/framework.ts, backend/app.ts and routes/. --report prints each chunk's size. --transport builds the client to reach its server through that module's fetch, for a native shell. --prerender (static target) also prerenders the named pages, comma-separated, whether or not their route exports prerender. |
nifra start [--port <n>] [--out <dir>] | Run the Bun build at <out>/server.js. |
nifra target [<target>] | Show the deploy target kept in nifra.config.ts, or switch it. nifra build emits that target when no --target is given. |
Check and gate
The gates to run before calling a change done, locally and in CI.
| Command | What it does |
|---|---|
nifra check [--lints-only] [--json] [--sarif] | Typecheck plus contract lints: a hand-rolled fetch() to your own API, an untyped client, backend code reached from browser code. --lints-only skips tsc; --sarif emits SARIF 2.1.0. |
nifra review [--diff <ref>] [--strict] [--fix] [--write] | A deterministic, evidence-backed review of the project or a diff. --fix plans the recipes it can apply; --fix --write applies them. |
nifra fix [--code <NF-code>] | Apply the registered recipe for a diagnostic, then print the diagnostics that remain. |
nifra doctor [--strict] [--auto-fix] [--target <t>] | Find undeclared imports and duplicate copies of @nifrajs/core, React and other identity-sensitive packages, and print production readiness. --auto-fix writes the safe dependency fixes. |
nifra port [--target <t>] [--ci] [--strict] | A feature-by-deploy-target matrix (in-memory stores, in-process cron and WebSockets, runtime globals, node: built-ins) with file:line evidence. --ci fails on a feature the target lacks. |
nifra routes [--json] [--modes] [--hooks] [--graph] | Every page and API route with its methods. --modes shows each page's render mode and fails against --target; --hooks lists the hooks each route runs; --graph draws the routes as Mermaid. |
nifra smoke [--fixture <file>] [--in-process] | The declared production smoke checks: SSR, the mounted API, 404s, headers, auth, contracts and hydration. |
nifra cdn-check <url> | Check a deployed page behind a CDN: served from cache, no internal headers reaching visitors, and soft navigations and slot swaps getting their own answer rather than the cached document. |
nifra i18n check [entry] [--strict] | Check i18n catalogs: coverage, missing and unused keys, ICU syntax, placeholder parity and plural cases. It imports the entry module. |
nifra verify [--release] | Run the verification gate plan against the project's package.json scripts; a gate with no script is reported, not run. --release adds the build, test, coverage and cross-runtime gates. |
Contracts and assurance
Lock the API contract, prove the security posture, and fail CI when either regresses. See Verification for the ladder these build.
| Command | What it does |
|---|---|
nifra snapshot [--out <file>] | Write the backend's API contract (routes and schemas) as JSON, api-snapshot.json by default: the baseline for nifra diff. |
nifra diff [<baseline>] | The breaking-change gate. A new required request field or a removed response field breaks; a new response field does not. Exits non-zero on a break. |
nifra contracts snapshot | check | Write the deterministic route contract lock, contracts.lock.json, or check the current routes against it. The lock records each declared part (body, query, params, headers, cookies, response, sse, each error status) with its top-level fields, so a failing check names the part and the fields that moved. |
nifra assure [--config <file>] | Classify every route against nifra.assurance.ts and list the evidence each one is missing. |
nifra assure --bundle [--strict] [--hydration] [--interact] | One JSON verdict over every applicable gate, each recorded as pass, fail or skip. Exits non-zero unless the verdict is green. |
nifra levels [--min <n>] | The verification ladder: L0 typed contract, L1 route assurance, L2 capability lockfile, L3 route manifest, L4 invariant-tested. --min fails below a level. |
nifra prove [--file <path>] [--min <n>] | Plan the cheapest proofs for the changed files and report a machine-checkable stop condition. Needs a fresh build. |
nifra capabilities snapshot | check | explain | Write the capability lockfile once provenance and idempotency assurance pass; fail CI on an effect import that bypasses it, drift, a GET that writes, or an idempotency gap; explain one route's tokens with explain <METHOD> <path>. |
nifra manifest emit | diff | Emit the hash-verified route trust manifest, signed with --sign <key-ref> through the configured KMS signer, or compare two manifests and fail on a regression. |
nifra replay <file> | Validate a token-only verification metadata file and run it against its gate. |
Generate
Write the files the types and clients come from.
| Command | What it does |
|---|---|
nifra types [--check] | Each route's ./+types module under .nifra/types: params, schema-typed data, and api typed by backend/app.ts. It also writes routes.d.ts, the route table href() reads. dev, build and check refresh them too. |
nifra schemas [--write] [--check] | Draft loaderOutput and actionOutput from each loader's and action's return type. --write adds the missing ones; it also lists returned fields a hand-written schema drops. |
nifra sync-manifest | Regenerate a committed server-manifest.ts from routes/ without a full build. |
nifra scaffold hole <route> <name> [--shared] [--interactive] [--timeout <ms>] [--server] | Add a hole to a partially prerendered route: its definition, boundaries entry and Hole in a JSX page, and a loader with its output schema in the backend half. A Vue or Svelte page gets the code to paste. |
nifra openapi [--format json | yaml] [--path <prefix>] | The backend's OpenAPI document, including response types inferred at build time. |
nifra sdk --lang python | go [--out <file>] | A deterministic Python or Go SDK generated from backend/app.ts. |
Agents and the dev server
What a coding agent reads and runs. nifra mcp serves the same information as tools; see Coding agents.
| Command | What it does |
|---|---|
nifra mcp [dir] | Start the project's MCP server over stdio: the route index, scaffolding, nifra_check, SSR rendering, the dev server's errors and logs, and the declared dev database. |
nifra docs-mcp [--port <n>] | Serve the public docs MCP (nifra_docs, nifra_example) over HTTP, on port 8787 by default. |
nifra context | Print the project's route index and conventions for an agent's prompt. |
nifra learn [<step>] | Print the guided build-an-app path, or one step's goal, actions and check. |
nifra shell tauri [--origin <url>] [--name <n>] [--id <bundle>] [--mobile android|ios|all] [--force] | Add a Tauri 2 shell to an existing app: frontend/shell-transport.ts and a src-tauri/ project that wraps a static build made with --transport. Writes files only and keeps any that exist unless --force; --mobile then runs tauri android init and tauri ios init. See native shells. |
nifra init-agents [--force] [--sync-mcp] | Add the agent files a new app ships (.mcp.json, the AGENTS.md sections, each agent's pointer) to an existing app. --sync-mcp re-pins the MCP launch to the installed nifra. |
nifra errors [--since <n>] [--category <c>] | What the running dev server caught (SSR, loader, API, build, browser and hydration errors), each a structured diagnostic. Exits 1 while errors are open. |
nifra logs [--level <l>] [--grep <s>] | The dev server's console, server and browser, each line tagged with its request. |
nifra explain [<message> | <NF-code>] | A structured diagnostic for an error, or what a check rule reports and how to fix it. |
nifra db schema | query | role | audit | Read the development database declared as devDatabase in nifra.config.ts: its tables, one read-only SELECT (rows capped, secrets masked), the SQL for a read-only Postgres role, and a log of what ran. |
Migrate and upgrade
Move an app between layouts and releases. Each one is a dry run until --write.
| Command | What it does |
|---|---|
nifra migrate layout [--write] [--zones] | Move an app onto the 4.0 layout: split each route into x.tsx and x.backend.ts, fold _middleware.ts into _layout.backend.ts, move backend.ts and framework.ts under backend/, and zone the other modules. |
nifra migrate --from tailwind --to stylex | Move static Tailwind classes to StyleX; see below. |
nifra upgrade <version> [--write] [--list] | Run every release recipe between the installed version and the target; see below. |
Tailwind to StyleX
Nifra includes a conservative codemod for moving static Tailwind classes to StyleX. It is a dry run by default, so inspect the proposed edits first:
nifra migrate --from tailwind --to stylex # report safe edits and manual issues
nifra migrate --from tailwind --to stylex --write # apply only safe edits
nifra migrate --from tailwind --to stylex --dir srcSupported static className attributes become stylex.props(...) calls backed by a local stylex.create(...) table. Responsive breakpoints and element-local pseudo-classes such as hover: are supported. Dynamic class expressions, arbitrary values, parent-dependent variants, and unknown utilities stay unchanged and are reported with file/line evidence. A non-zero exit status means manual migration issues remain.
StyleX compilation is native to Nifra's Bun pipeline. Install the runtime and compiler peers, then register both the browser and SSR transforms:
# Install the runtime and the optional compiler peers.
bun add @stylexjs/stylex
bun add -d @babel/core @stylexjs/babel-plugin @babel/plugin-syntax-flow \
@babel/plugin-syntax-jsx @babel/plugin-syntax-typescript// nifra.config.ts - Bun's client and SSR build transforms.
import { stylexBunPlugin } from "@nifrajs/web/plugins/stylex"
export const clientPlugins = [stylexBunPlugin("dom")]
export const serverPlugins = [stylexBunPlugin("ssr")]If the project intentionally uses Vite, add the Vite adapter alongside its existing Vite transforms. Nifra will use Vite when vitePlugins are the app's only transforms:
// doc-check: skip - requires the third-party Vite React plugin
// If the app intentionally uses Vite, keep StyleX in vitePlugins.
import react from "@vitejs/plugin-react"
import { stylexVite } from "@nifrajs/web/plugins/stylex"
export const vitePlugins = [react(), stylexVite()]Upgrading nifra
Every @nifrajs/* package, nifra and create-nifra ship together at one version. Move a workspace between releases with nifra upgrade <version> rather than by editing pins: it runs every release recipe between the oldest version your package.json files pin and the target, oldest first. A recipe moves a removed package to its replacement, rewrites imports that moved, lists comments a release stopped honoring, and pins each group dependency to the target, keeping its ^ or ~ unless you pass --exact. The pins in overrides, resolutions and pnpm.overrides move with them, since an override decides what installs. A peerDependencies range is what a library accepts, not a pin: it is raised only when it excludes the target (keeping its operator, even with --exact), and a library's ">=3.1.0" floor never sets the version the upgrade starts from unless nothing else, installed or declared, names one.
nifra upgrade --list # the release targets this CLI knows
nifra upgrade 5.14.0 # dry-run: every planned edit, nothing written
nifra upgrade 5.14.0 --write # apply; it verifies with nifra check once the target is installed
# if pins were already bumped by hand, add --from <installed-version>
bun install # install the new pins
nifra check # verify against them
nifra doctor # afterwards: no "mixed nifra versions" advisory leftIt is a dry-run until --write, and the same run twice makes no further edits. Once the pins name the target, no recipe is left to apply: pass --from <version> with the version they were at to apply the ones they skipped. An option it does not know is refused rather than ignored. An unknown version or a target below what is installed is refused (--allow-downgrade when the rollback is intended); a target newer than the running CLI prints the command for that release's CLI. It edits files under the workspace root only: a symlinked package directory or package.json is never followed, and a group package installed by a link from outside the root is listed under "Left alone" for you to upgrade in its own repository. The MCP launch pin in .mcp.json, .cursor/mcp.json, CLAUDE.md and AGENTS.md moves to the target, or is dropped when the project declares @nifrajs/cli so the launch runs that install from then on: the edit nifra init-agents --sync-mcp makes. Another version pinned outside package.json is listed with its line: the rest of an agent file, an MCP config elsewhere, a Dockerfile or compose file, a CI workflow, and a lockfile other than the workspace's own (an image build's frozen lockfile, say), which you regenerate after installing. nifra check reads the installed packages, so --write runs it (--no-verify skips that) only once they match the target: until the new pins are installed it would judge the release you are leaving, and the command prints the install to run first instead. With --write it also saves the hook report from before the edits and, once the target is installed, prints how hook scope changed across the upgrade (--no-hooks skips that); before then, nifra routes --hooks --since .nifra/hooks-before-upgrade.json compares after the install. Run from a CLI whose @nifrajs/core is not the project's - bunx @nifrajs/cli@<new> upgrade before the new release is installed - it takes no hook report, since that copy cannot reflect the project's app, and says so in one line. nifra doctor and nifra check (NF-D002) point here when a workspace carries more than one version; see mixed nifra versions. A file: package whose dependencies this upgrade moves keeps its old ones in bun.lock, where Bun never refreshes them; the plan lists each, and --write drops those entries so the next bun install records them again (see stale file: links).
A link: or file: dependency outside the root that installs its own @nifrajs/* at another version stops the upgrade before anything is written: its imports resolve from its own node_modules, so after the upgrade a server() it builds cannot be merged into yours. The refusal names each one with the commands that move it to the target; upgrade those first, or pass --allow-linked-skew to go ahead. nifra upgrade --list shows the targets with the notes of every release after the one you declare: what an app can observe changing on the way up.
A release recipe names the packages its notes change. When none of them is one the project loads (every group package a package.json names, and what those depend on as installed), the list and the plan say so beside the release: no announced behaviour change for this project, with the packages it does change. A tool such as @nifrajs/cli counts when it is declared, without its own dependencies, since a release that changes what a tool does names the tool. A release without that list, or a declared package that is not installed, is never marked.
Releases and support
Behaviour changes ship in minor releases; fixes ship as patches of the latest version and change nothing an app relies on. Only the latest release is supported: security fixes and fixes for data loss ship as patches of it, so move to the latest with nifra upgrade. SECURITY.md lists the supported versions.
Scope
nifra build defaults to a self-hosted Bun server. Use --target node, deno, cloudflare, vercel, or static for another complete deploy shape (see Deployment). Run non-Bun outputs with the command printed by the build.