Installation

Install zfb with npm / pnpm or as a standalone binary without Node.

@takazudo/zfb ships as an npm package that pulls a prebuilt platform binary via npm optional-deps — no Rust toolchain required.

Choose one of two installation paths: use npm / pnpm for a Node-based project, or install the standalone binary without Node.

The following prerequisites apply to the npm / pnpm path.

The standalone and npm distributions provide the same CLI and commands; choose how to install it, not a different engine.

Prerequisites

You will need:

• Node.js ≥ 22 — required by the npm CLI wrapper and by the tsc subprocess that powers zfb check. The default TypeScript config loader itself runs inside zfb's embedded V8 runtime, not Node.

• pnpm ≥ 10 — install via the official installer. This matches the minimum declared in the published @takazudo/zfb package's engines field; zfb scaffolds projects that use pnpm and will run pnpm install for you when it can find pnpm on your PATH. Contributors building the zfb monorepo itself need a newer pnpm — see From source (contributors) below.

Supported platforms

@takazudo/zfb ships a prebuilt platform binary via npm optional-deps for:

Install the CLI

Install @takazudo/zfb as a dev dependency in your project:

pnpm add -D @takazudo/zfb

npm install -D @takazudo/zfb

Verify the install

For a standalone installation, run zfb --version and zfb --help. For npm / pnpm, use the following command.

npx zfb --help

You should see seven subcommands:

• zfb new — scaffold a new project

• zfb dev — start the dev server with watcher and live-reload

• zfb build — produce a static build

• zfb css — compile a CSS entrypoint without building the site

• zfb wind — explain and audit zudo-wind candidates and generate manifests

• zfb preview — serve the build output

• zfb check — typecheck the project and validate content collections against their schemas

If npx zfb --help prints all seven, you're ready to move on to Your first site.

From source (contributors)

If you are contributing to zfb itself and need to build the CLI from source, see BUILDING.md for full instructions including the Rust toolchain prerequisites.

The short path:

git clone https://github.com/Takazudo/zudo-front-builder.git
cd zudo-front-builder
pnpm install --frozen-lockfile
cargo install --path crates/zfb

crates/zfb/build.rs embeds Hono from the workspace pnpm store, so install the workspace's JavaScript dependencies first; without them the build stops and asks for pnpm install --frozen-lockfile. The first build compiles V8 and takes 15 to 30 minutes.

Install without Node

zfb ships as a self-contained Rust binary. Node.js is not required to install or run it. Rolldown, the default bundler for pages and islands, and zudo-wind are compiled into the zfb binary and run in process. esbuild is embedded in the zfb executable's vendor snapshot, extracted at runtime, and invoked as a subprocess to compile zfb.config.ts and plugins (and to bundle pages and islands when ZFB_BUNDLER=esbuild is set). None of them is shipped as a separate release-tarball binary next to zfb. You only need Node as an opt-in escape hatch for specific features (see When Node is still needed below).

The Node-free path supports the full feature set for content sites: Markdown, MDX, HTML pages, and islands — Rolldown and zudo-wind are part of the binary itself, and esbuild runs as a standalone native binary extracted by zfb. Client-side hydration and CSS processing therefore work with zero Node involvement. See Styling for the CSS engine and authored-stylesheet contract.

Standalone supported platforms

Install paths

Linux / macOS — curl

curl -fsSL https://raw.githubusercontent.com/Takazudo/zudo-front-builder/main/install.sh | sh

Installs zfb to $HOME/.local/bin/zfb. Add that directory to your PATH if it isn't already:

export PATH="$HOME/.local/bin:$PATH"

Environment variables:

macOS — Homebrew

brew install Takazudo/tap/zfb

The tap is hosted at Takazudo/homebrew-tap. The formula is updated on each stable release by scripts/update-homebrew-formula.sh.

To update to a newer version later:

brew upgrade zfb

Windows — PowerShell

irm https://raw.githubusercontent.com/Takazudo/zudo-front-builder/main/install.ps1 | iex

Installs zfb.exe to %LOCALAPPDATA%\zfb\bin\zfb.exe.

Environment variables:

Add the binary to your PATH for the current session:

$env:PATH = "$env:LOCALAPPDATA\zfb\bin;$env:PATH"

Or permanently (open a new terminal after running):

[System.Environment]::SetEnvironmentVariable(
  'PATH',
  "$env:LOCALAPPDATA\zfb\bin;" + [System.Environment]::GetEnvironmentVariable('PATH', 'User'),
  'User'
)

Windows — Scoop

Verify the standalone install

zfb --version

Config file: zfb.config.json vs zfb.config.ts

Both config formats work without Node. zfb.config.ts is evaluated in-process via the embedded V8 isolate that ships with the default zfb binary — there is no runtime Node dependency.

zfb.config.ts is a data config — node:* imports, process.env, and other Node-only APIs are not available inside the evaluator. Use zfb.config.ts when you want TypeScript types, comments, and computed values. Use zfb.config.json for a plain JSON alternative.

// zfb.config.json — also Node-free compatible
{
  "outDir": "dist",
  "collections": [
    {
      "name": "blog",
      "path": "content/blog",
      "schema": { "type": "object", "properties": { "title": { "type": "string" } } }
    }
  ]
}

If both zfb.config.ts and zfb.config.json are present, the .ts file wins.

When Node is still needed

The following features require Node in PATH:

Everything else — building, dev server, islands, zudo-wind, MDX, content collections, and zfb.config.ts evaluation — runs Node-free.

Upgrading zfb

There is no zfb upgrade subcommand. To update, re-run the same install command you used initially — it overwrites the existing binary with the latest version.