CLI リファレンス

zfb コマンドラインインターフェースの完全なリファレンス — サブコマンド、フラグ、環境変数。

概要

zfb バイナリは、開発ライフサイクル全体をカバーする 5 つのサブコマンドを提供します。

zfb new    — テンプレートから新しいプロジェクトをスキャフォールドする
zfb dev    — ライブリロード付きのローカル開発サーバー
zfb build  — プロダクションビルド
zfb preview — ビルド済みサイトを配信する
zfb check  — 型チェックとコンテンツコレクションのスキーマ検証

zfb --help または zfb <subcommand> --help を実行すると、生成されたヘルプテキストを直接確認できます。

zfb new

組み込みテンプレートから新しいプロジェクトをスキャフォールドします。

zfb new <name> [--template <template>]

引数

テンプレート

v0 は 2 つのテンプレートを同梱しており、どちらもコンパイル時に crates/zfb/templates/ からバイナリに焼き込まれています。

• basic-blog（デフォルト）— package.json を備えたフル機能のブログスキャフォールド。pnpm が PATH にある場合、zfb new は自動的に pnpm install を実行します。

• node-free — package.json を同梱せず、スキャフォールド後の pnpm install ステップも完全にスキップします。PATH に Node / pnpm がない環境で実行するプロジェクト向けです。.md/.html によるページ作成については Markdown と HTML ページ を、Node なしで zfb バイナリ自体をインストールする方法については Node なしでインストール を参照してください。

例

zfb new my-site
zfb new my-site --template basic-blog
zfb new my-site --template node-free

zfb dev

ライブリロード付きのローカル開発サーバーを起動します。

zfb dev [--port <port>] [--host [<host>]]

フラグ

* 次の順にフォールバックします: CLI フラグ → zfb.config.json の port/host → 組み込みのデフォルト。

遅延レンダリング

dev サーバーはデフォルトで 遅延レンダリング を行います: 変更されたルートは stale とマークされ、すべてのファイル変更時に即座にではなく、最初のリクエスト時に再レンダリングされます。これにより、大規模サイトでも開発のインナーループを高速に保ちます。

遅延以前の挙動に戻し、各ファイル変更時に影響を受けるすべてのルートを即座に再レンダリングするには、ZFB_DEV_EAGER=1 を設定します。

環境変数

例

# デフォルト — localhost:3000 にバインドします
zfb dev

# カスタムポート
zfb dev --port 8080

# LAN に公開する（0.0.0.0）
zfb dev --host

# ホストを明示的に指定
zfb dev --host 192.168.1.10 --port 4321

zfb build

プロジェクトをプロダクション向けにビルドします。静的 HTML（およびアダプタが設定されている場合はサーバーエントリ）を出力ディレクトリに出力します。

zfb build [--outdir <dir>] [--minify-html | --no-minify-html]
          [--strict-broken | --no-strict-broken]

フラグ

HTML ミニファイは、minifyHtml: true を設定するか --minify-html を渡さない限りデフォルトでオフです。zfb の Rust 側の後処理パイプライン内で実行され、Node.js のミニファイ subprocess は起動しません。初回バージョンは保守的で、レンダリングされた HTML ページだけを対象候補にし、ソースが .html の passthrough ページはそのまま残し、HTML 以外の出力はスキップします。

壊れたリンクによる strict なゲートも同様にデフォルトではオフです。--strict-broken と --no-strict-broken は排他で、同時に渡すとエラーになります。どちらも strictBrokenLinks 設定フィールドより優先され、その設定フィールドがデフォルトの false より優先されます。どちらのフラグも zfb build にのみ影響します。zfb dev が strict オーバーレイを見ることはなく、自分で書いた linkValidation 設定どおりのリンク検証の挙動をそのまま保ちます。resolveMarkdownLinks.onBrokenLinks との違いを含む挙動の全体はリンク検証 — strict モードを参照してください。

例

zfb build
zfb build --outdir public
zfb build --minify-html
zfb build --no-minify-html
zfb build --strict-broken
zfb build --no-strict-broken

zfb preview

ビルド済みのサイトをローカルで配信します。先に zfb build を実行してください。

zfb preview [--port <port>] [--host [<host>]] [--outdir <dir>]

静的モード（アダプタなし、または adapter: "none"）では、zfb preview は zfb dev と同じ2つのリクエスト時レイヤーを、通常の静的ファイル配信より前段で実行します: プラグインの previewMiddleware 登録、続いて public/_redirects（Static Assets — _redirects を参照）。同じ URL に対してプラグインが _redirects のルールより常に優先されます。

_redirects のマッチャーに到達するのは GET/HEAD リクエストのみです — これは実際の Workers Static Assets がアセット層（したがって _redirects）をこの2つのメソッドに対してしかプローブしない挙動を反映しています。それ以外のメソッドはプラグインハンドラ（すべてのメソッドを受け付けます）に到達するか、405 になります。GET /old-page に対して発火するはずのルールが POST /old-page では決して発火しません。

zfb.config.json の adapter フィールドがサポート対象のアダプタ（例: @takazudo/zfb-adapter-cloudflare）を指定している場合、zfb preview は zfb 自身の静的サーバーではなく wrangler dev に処理を引き渡します。この場合、--outdir または config の outDir から選ばれた出力ディレクトリは、存在するかを事前確認するだけになります。実際に何を配信するかは wrangler 自身の設定が制御するためです。SSR と Cloudflare バインディング を参照してください。

アダプタの preview は、処理を引き渡す前に pnpm exec wrangler --version の事前チェックを実行し、zfb がテスト済みのベースラインを 最小サポートバージョン として扱います。それより古い wrangler はアップグレード案内とともに中断しますが、同じかそれより新しいものは続行します（新しいバージョンでは情報行を、未テストのメジャーバージョンでは警告を出力します）。ZFB_SKIP_WRANGLER_VERSION_CHECK=1 は、一時的な escape hatch としてのみ設定してください（例: wrangler のバージョン出力形式が変わった場合）。

フラグ

* 次の順にフォールバックします: CLI フラグ → zfb.config.json の port/host → 組み込みのデフォルト。

出力ディレクトリも同様に、CLI の --outdir → config の outDir → 組み込みの dist の順でフォールバックします。

例

zfb build && zfb preview
zfb preview --port 8080
zfb preview --host --outdir public

zfb check

プロジェクトの型チェックを行い、コンテンツコレクションのフロントマターをスキーマに対して検証します。

zfb check [--skip-tsc]

このコマンドは 2 つのチェックを実行します。

1. TypeScript — tsc --noEmit をサブプロセスとして呼び出します。zfb.config.ts、コレクションスキーマ、src/ の型エラーを捕捉します。

2. コレクションスキーマの検証 — 各コレクションエントリのフロントマターを、zfb.config.json/zfb.config.ts の各コレクションの schema フィールドで宣言された JSON Schema に対して検証します。ビルド自体はフロントマターを検証しないため、これが強制の関門となります。

いずれの失敗モードも非ゼロのコードで終了します。

フラグ

例

# フルチェック — tsc + スキーマ検証
zfb check

# スキーマのみ（tsc をスキップ）
zfb check --skip-tsc

環境変数

以下の環境変数は zfb 全体に影響します（特定のサブコマンドに固有のものではありません）。