インストール

npm / pnpm または Node 不要のスタンドアロンバイナリで zfb をインストールする。

@takazudo/zfb は npm パッケージとして配布され、npm の optional-deps 経由でビルド済みのプラットフォームバイナリを取得します。Rust ツールチェインは不要です。

インストール方法は 2 つあります。Node を使うプロジェクトでは以下の npm / pnpm を、Node を入れない場合はスタンドアロンのインストールを選んでください。

以下の前提条件は npm / pnpm 経由の場合に必要です。

スタンドアロンと npm は同じ CLI とコマンドの配布方法です。エンジンの機能を選び分けるものではありません。

前提条件

以下が必要です。

• Node.js ≥ 22 — npm CLI ラッパーと、zfb check を支える tsc サブプロセスに必要です。デフォルトの TypeScript 設定ローダー自体は Node ではなく、zfb の組み込み V8 ランタイム内で動きます。

• pnpm ≥ 10 — 公式インストーラー からインストールしてください。これは公開されている @takazudo/zfb パッケージの engines フィールドで宣言されている最小バージョンと一致します。zfb は pnpm を使うプロジェクトをスキャフォールドし、PATH 上に pnpm が見つかる場合は pnpm install を自動で実行します。zfb モノレポ本体をビルドするコントリビューターは、より新しい pnpm が必要です — 下記の「ソースからビルドする（コントリビューター向け）」の節を参照してください。

サポートされているプラットフォーム

@takazudo/zfb は npm の optional-deps 経由で、以下のプラットフォーム向けにビルド済みバイナリを配布しています。

CLI のインストール

@takazudo/zfb をプロジェクトの開発依存としてインストールします。

pnpm add -D @takazudo/zfb

npm install -D @takazudo/zfb

インストールの確認

スタンドアロンでインストールした場合は zfb --version と zfb --help で確認できます。以下は npm / pnpm の場合です。

npx zfb --help

7 つのサブコマンドが表示されるはずです。

• zfb new — 新しいプロジェクトをスキャフォールドする

• zfb dev — ウォッチャーとライブリロード付きの開発サーバーを起動する

• zfb build — 静的ビルドを生成する

• zfb css — サイトをビルドせずに CSS エントリポイントをコンパイルする

• zfb wind — zudo-wind の候補を説明、監査し、マニフェストを生成

• zfb preview — ビルド出力を配信する

• zfb check — プロジェクトを型チェックし、コンテンツコレクションをスキーマに照らして検証する

npx zfb --help で 7 つすべてが表示されれば、Your first site に進む準備ができています。

ソースからビルドする（コントリビューター向け）

zfb 本体にコントリビュートしていて CLI をソースからビルドする必要がある場合は、Rust ツールチェインの前提条件を含む詳しい手順を BUILDING.md で確認してください。

最短の手順:

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 はワークスペースの pnpm store から Hono を埋め込むため、先に JavaScript の依存関係をインストールしてください。インストールしていないとビルドが停止し、pnpm install --frozen-lockfile の実行を求めます。初回ビルドは V8 のコンパイルを含み、15〜30 分かかります。

Node なしでインストール

zfb は自己完結型の Rust バイナリとして配布されます。インストールにも実行にも Node.js は不要です。 ページと islands のデフォルトのバンドラーである Rolldown と zudo-wind は zfb バイナリ自体にコンパイルされており、プロセス内で動作します。esbuild は zfb 実行ファイルの vendor snapshot に埋め込まれ、実行時に展開されてサブプロセスとして呼び出され、zfb.config.ts とプラグインをコンパイルします（ZFB_BUNDLER=esbuild を設定した場合はページと islands のバンドルも担当します）。いずれも zfb の隣に別の release tarball バイナリとして配布されません。Node が必要なのは一部の機能をオプトインで使う場合だけです（下記の Node が依然として必要なケース を参照してください）。

Node なしでも、コンテンツサイト向けの Markdown、MDX、HTML ページ、islands を利用できます。Rolldown と zudo-wind はバイナリ自身の一部で、esbuild は zfb が展開するネイティブバイナリとして動作します。クライアントサイドのハイドレーションと CSS 処理にも Node は不要です。CSS エンジンと手書き CSS の契約は スタイリング を参照してください。

スタンドアロンの対応プラットフォーム

インストール経路

Linux / macOS — curl

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

zfb は $HOME/.local/bin/zfb にインストールされます。このディレクトリがまだ PATH に含まれていない場合は追加してください：

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

環境変数：

macOS — Homebrew

brew install Takazudo/tap/zfb

tap は Takazudo/homebrew-tap でホストされています。formula は 安定版リリースごとに scripts/update-homebrew-formula.sh によって更新されます。

後から新しいバージョンへ更新するには：

brew upgrade zfb

Windows — PowerShell

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

zfb.exe は %LOCALAPPDATA%\zfb\bin\zfb.exe にインストールされます。

環境変数：

バイナリを現在のセッションの PATH に追加するには：

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

恒久的に追加する場合（実行後は新しいターミナルを開いてください）：

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

Windows — Scoop

スタンドアロンの確認

zfb --version

設定ファイル：zfb.config.json と zfb.config.ts

どちらの設定フォーマットも Node なしで動作します。zfb.config.ts は、デフォルトの zfb バイナリに同梱された組み込み V8 アイソレートによってインプロセスで評価されます — 実行時の Node 依存はありません。

zfb.config.ts はデータ設定です — node:* のインポート、process.env、その他 Node 専用 API は評価器内では利用できません。TypeScript の型・コメント・計算値が 欲しい場合は zfb.config.ts を、プレーンな JSON で済ませたい場合は zfb.config.json を使ってください。

// zfb.config.json — こちらも Node なしで動作します
{
  "outDir": "dist",
  "collections": [
    {
      "name": "blog",
      "path": "content/blog",
      "schema": { "type": "object", "properties": { "title": { "type": "string" } } }
    }
  ]
}

zfb.config.ts と zfb.config.json の両方が存在する場合は .ts ファイルが 優先されます。

Node が依然として必要なケース

以下の機能は PATH 上に Node が必要です：

それ以外 — ビルド、開発サーバー、islands、zudo-wind、MDX、コンテンツコレクション、 zfb.config.ts の評価 — はすべて Node なしで動作します。

zfb のアップグレード

zfb upgrade サブコマンドはありません。 現時点では、最初に使ったインストールコマンドを再実行してください — 既存のバイナリを 最新バージョンで上書きします。