CLI リファレンス

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

概要

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

zfb new    — テンプレートから新しいプロジェクトをスキャフォールドする
zfb dev    — ライブリロード付きのローカル開発サーバー
zfb build  — プロダクションビルド
zfb css    — サイトをビルドせずに CSS エントリポイントをコンパイルする
zfb wind   — ユーティリティ候補とソースでの使用状況を調べる
zfb preview — ビルド済みサイトを配信する
zfb check  — 型チェックとコンテンツコレクションのスキーマ検証

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

日々の手順は zfb で作る を参照してください。テスト、lint、format、deploy、upgrade のサブコマンドはありません。プロジェクトや配信先のツールを使います。

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>]]
        [--scratch-dir <path>] [--define <KEY=EXPR>]...

フラグ

* 次の順にフォールバックします: 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]
          [--strict-content-bridge | --no-strict-content-bridge]
          [--strict-plain-css-imports | --no-strict-plain-css-imports]
          [--scratch-dir <path>] [--warnings-json <file>]
          [--define <KEY=EXPR>]...

フラグ

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 モードを参照してください。

MDX コンテンツブリッジとプレーン CSS import のゲートもデフォルトではオフです。それぞれの有効・無効フラグを同時に渡すとエラーになり、どちらかを明示すると対応する設定フィールド（デフォルト false）より優先されます。これらのフラグが影響するのは zfb build だけです。zfb dev は引き続き MDX のフォールバックを警告して配信し、プレーン CSS import の警告もエラーにしません。設定フィールドは define-config を参照してください。

環境変数

例

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 build --strict-content-bridge
zfb build --no-strict-content-bridge
zfb build --strict-plain-css-imports
zfb build --no-strict-plain-css-imports
zfb build --scratch-dir .zfb-build/ci --define __ORIGIN__='"https://www.example.com"'

ビルド警告 JSON

zfb build --warnings-json warnings.json は診断をファイルに保存します。schemaVersion: 1、command: "build"、status、diagnostics を持ちます。status は success、failed、incomplete のいずれかで、後者 2 つの診断は部分的な場合があります。レコードは決定的な順序で並びます。同じ警告が複数回発生した場合は各発生が残ります。警告は従来の終了コードを変更しません。

診断のない成功したビルドは diagnostics: [] を書き込みます。早期に失敗したビルドは、それまでに得られた診断（空の場合もあります）を failed レポートに書き込みます。出力先の親ディレクトリは事前に存在している必要があります。書き込み失敗は報告され、ビルドコマンドも失敗します。

各レコードには code、severity、message があり、sourceId、file、line、byteColumn は分かる場合のみ付きます。byteColumn は 1 始まりの UTF-8 バイト列です。sourceId は不透明な識別子で、必ずしもパスではありません。文言ではなくコードを機械処理に使い、未知のコードも許容してください。

ZW001–ZW014 は既存の Wind 診断コードです。Wind の sourceId は不透明です。監査専用の ZW015 と ZW016 はビルド警告 JSON に入りません。

zfb css

Node.js の同一プロセス内で、メモリ上の設定を使い、出力ファイルを省略してコンパイルするには compileCss を使います。CLI も同じコンパイラーを呼び出します。

ルートの探索、ページのレンダリング、アプリケーションコードのバンドル、プラグインホストの起動を行わずに、1 つの CSS エントリポイントを zudo-wind と zfb の手書き CSS 処理でコンパイルします。

zfb css --input <entry.css> --output <compiled.css>
        [--project-root <dir>] [--config <file>]
        [--source <glob> ...]
        [--no-auto-source]
        [--code-highlight-mode <class|inline>]
        [--no-default-highlight-styles]

フラグ

例

ユーティリティの値はプロジェクトの config で指定し、ソース glob でプロジェクト内の候補を見つけます。この例では、インストール済みパッケージの exports map が公開する CSS サブパス（@example/design-system）も読み込みます。

import { defineConfig } from "zfb/config";

export default defineConfig({
  wind: {
    tokens: {
      spacingUnit: "0.25rem",
      colors: {
        brand: "oklch(0.65 0.2 250)",
      },
      radii: {
        card: "0.5rem",
      },
    },
    authoredClasses: {
      example: true,
    },
    manifests: {
      "design-system": { path: "@example/design-system/wind.json" },
    },
  },
});

インストール済みパッケージは ./base.css と ./wind.json を公開します。dist/wind.json の内容は次のとおりです。

{
  "schemaVersion": 1,
  "specVersion": 1,
  "producer": "design-system",
  "candidates": ["bg-brand", "p-4", "rounded-card"]
}

パッケージの候補が使うトークンはプロジェクト側で設定します。

export function ExampleCard() {
  return <article className="example flex p-4 bg-brand rounded-card">Example</article>;
}

このエントリには手書き CSS と @import だけを記述し、Tailwind ディレクティブは含めません。

@import "@example/design-system/base.css";

.example {
  border: 1px solid var(--zw-color-brand);
}

プロジェクトのルートから実行します。glob でプロジェクト自身のソースを走査し、設定済み manifest から design-system パッケージの候補を追加します。

zfb css \
  --input src/styles/entry.css \
  --output dist/app.css \
  --project-root . \
  --source 'src/**/*.{tsx,ts,jsx,js}' \
  --no-auto-source

@import のパスは手書き CSS として解決・結合されます。zudo-wind は zfb.config.ts から utility の値を読み、--source でローカル候補を探し、wind.manifests からパッケージ候補を読みます。

補足

• ソースは設定済みのソースプランに従います。 --source は明示的な入力を追加します。--no-auto-source は慣例的なルートを除外しますが、明示的な入力と codeHighlight.roleClasses のクラスは維持します。慣例的なルートの走査では、node_modules、dist、build、target、.git、.cache、.turbo、.next、.vercel、.zfb-build、.zfb という名前のサブディレクトリをスキップします。ただし、明示的な --source の glob がそれらのディレクトリ内で一致したファイルは読み込みます。パッケージのソースルートは wind.sources.packageRoots か --source で宣言するか、パッケージ側で wind.manifests を使って候補を公開できます。すべてのルートからファイルを取り除くには wind.sources.exclude を使います。プロジェクトの設定済み outDir、--output のパス、zfb のスクラッチルートは引き続き除外されます。明示した --source の一致がすべてこれらの出力ルート内にあるか wind.sources.exclude のパターンに一致する場合、zfb css は ZW010 エラーを報告します。一部だけが除外される場合は ZW010 警告を報告し、残りのファイルを走査します。たとえば、dist が設定済み outDir の場合、--source 'dist/**/*.tsx' はエラーを報告します。build と dev はデフォルトで .tsx、.ts、.jsx、.js、.mdx、.md を走査します。単独コマンドの明示的な入力では .html と .mjs も使えます。詳しくは ソースと候補 を参照してください。

• 出力は決定的で、アトミックに置き換えられます。 エントリ、config、ソース一式とその指定順が同じなら、タイムスタンプ、ソースマップ、一時パスを含まない同一のバイト列が生成されます。コンパイルに成功したときだけ --output がアトミックに置き換えられ、失敗時には既存の出力がそのまま保たれます。

• グローバル CSS のみが対象です。 CSS Modules の探索や処理は行いません。パッケージ由来の url() によって別ファイルの出力が必要になる場合、v1 では付随アセット（companion asset）をスタイルシートの隣に書き出さず、非ゼロ終了で拒否します。

• config の利用範囲は限定的です。 --config のファイル、またはプロジェクトの zfb.config.json か zfb.config.ts があれば、wind のトークン、リセット、ソース、および classPrefix や roleClasses などのハイライト設定を読み込みます。CLI のハイライトフラグは対応するモードとスタイルシートの選択を上書きします。wind: false は wind の生成を無効にしますが、手書き CSS とハイライトの処理は続きます。キーを省略すると空の有効な wind 設定になります。

• v1 の wind 出力はミニファイされません。 生成 CSS には カスケードとリセット で説明する固定のプリンタを使います。

明示的な config ファイル

スタイルシートを配布するパッケージには自身のサイト config がありませんが、そのクラスは利用側が実行する設定のトークンを使います。--config <file> を使うと、パッケージをサイトに見せかけることなく、プリセットを含めて通常の config ローダーでその設定を読み込めます。

cd packages/ui
zfb css \
  --input src/styles/entry.css \
  --output dist/ui.css \
  --config ../../site/zfb.config.ts \
  --project-root . \
  --source 'src/**/*.tsx' \
  --no-auto-source

基準となるディレクトリは 2 つあります。

• config ファイルのディレクトリは、config に書かれたすべての参照の基準です。相対パスの wind.manifests、wind.sources.packageRoots、wind.sources.exclude のパターンが該当します。プリセットが宣言する参照は引き続きそのパッケージのディレクトリを基準にし、プリセットのパッケージ自体は config ファイルのディレクトリから解決されます。

• プロジェクトルートは、コマンド自身の入力の基準です。--source の glob、慣例的なソースルート、設定済み outDir の除外が該当します。--project-root を省略すると、config ファイルのディレクトリになります。

zfb wind explain と zfb wind audit も同じ --config フラグを受け付けるため、1 つの config ファイルでコンパイル、監査、候補の確認を行えます。--config を指定しない場合、どのコマンドも従来どおりプロジェクトルートで zfb.config.ts または zfb.config.json を探します。

zfb wind

zfb wind explain は候補の解析、解決、出力を調べます。カタログ項目、トークンとの結び付き、宣言、セレクタ、条件、順序の情報を表示します。

zfb wind explain [--project-root <path>] [--config <file>] [--json] <candidate>
zfb wind explain [--project-root <path>] [--config <file>] [--json] --stdin
zfb wind explain -- -mt-4

--config <file> は、明示的な config ファイル で説明するとおり、プロジェクトルートで探す代わりに zfb の config ファイルを読み込みます。負の値のユーティリティのようにダッシュで始まる候補は、オプションとして解釈されないよう -- の後に書きます。--stdin は空でない行ごとに 1 つの完全な候補を読み、設定を 1 回だけ読み込んで、入力順に重複も残したまますべてを説明します。--json は標準出力に { "schemaVersion": 1, "command": "explain", "explanations": [...] } だけを出力します。

zfb wind audit は通常のクラス位置の名前、存在しない・使われていないユーティリティ、動的なクラス断片、単一のクラスリストリテラル内のプロパティ衝突を調べます。完全一致の authoredClasses と group/peer マーカーは除外されます。wind: false の場合、explain は生成が無効であることを報告し、audit は空の候補レポートを返します。

zfb wind audit [--project-root <path>] [--config <file>] [--fail-on error|warning]
               [--plan standalone|build]
               [--severity error|warning|auditInfo] [--group] [--json]

--plan standalone（既定）は、--source なしの zfb css と同じルート、つまり規約上のプロジェクトルートと、設定された wind.sources のパッケージルートと除外を監査します。--plan build は zfb build と zfb dev が走査するソースプランを監査します。プラグインの setup を実行して、パッケージ所有のルート、兄弟ミラールート、プラグインの仮想モジュールを見つけ、仮想モジュールは plugin/<specifier> として監査します。preBuild と postBuild フックは実行せず、ビルド出力も書き込みません。どちらのモードでも、最初に wind audit plan: <mode> と、走査するすべてのルート、仮想モジュール、マニフェスト、除外とその理由を出力します。

--severity は指定した重大度以上の診断だけを表示します。出力を絞り込むだけで、終了ステータスは変わりません。--group はテキスト出力専用です。未認識クラスは候補名ごと、dead class と診断は候補名・コード・severity ごとにまとめ、出現数と決定的なレポート順で最初に現れる origin を表示します。診断の要約には、最初の発生位置のメッセージと、あれば推奨表記も残ります。既定のテキスト形式と終了ステータスは変わりません。--json はテキストの代わりに標準出力へ { "schemaVersion": 1, "command": "audit", "severity", "coverage", "report" } を出力します。--json と --group を同時に指定しても JSON ドキュメントと出現ごとの配列は変わりません。coverage オブジェクトにはプランのモード、ルート、仮想モジュール、マニフェスト、除外が入ります。各由来には sourceId、1 始まりの line、1 始まりのバイト列 byteColumn、別の値として byteOffset があり、該当しないフィールドは null です。状態の案内と失敗は引き続き標準エラーに出力します。

監査が完了した場合、デフォルトではエラー重大度の指摘があっても終了ステータスは 0 です。その場合、標準エラーに --fail-on error の案内が表示されます。設定が無効な場合、またはソースの走査に失敗した場合は非ゼロで終了します。--fail-on error はエラー重大度の診断があると非ゼロで終了し、--fail-on warning は警告も対象にします。auditInfo の指摘はどちらのしきい値にも影響しません。wind: false の場合、生成無効のレポートを返して終了ステータス 0 で終了します。

これらのコマンドは設定済みのプロジェクトを調べます。クラス候補の探索のためにアプリケーションコードは実行しません（--plan build でのプラグインの setup を除きます）。結果と由来については 診断とツール を参照してください。

zfb wind manifest

パッケージが利用側に公開する候補マニフェストを、zfb css と同じソースプラン、抽出器、コンパイラで生成します。

zfb wind manifest --producer <id> --output <file>
                  [--source <glob> ...] [--no-auto-source]
                  [--project-root <dir>] [--config <file>] [--json]

--producer はマニフェストの producer ID（[A-Za-z0-9][A-Za-z0-9._/-]*）で、利用側はこのキーで wind.manifests にファイルを宣言します。--output は現在の作業ディレクトリを基準に解決されます。--source、--no-auto-source、--project-root、--config は zfb css と同じように動作します。明示的な config ファイル を参照してください。

走査したソース内の候補の出現はすべて、1 回のコンパイルで分類されます。

• 解決されたユーティリティと group/peer マーカーがマニフェストになります。バイト順に並べ、重複は除きます。

• authoredClasses に一致するクラスと通常の単語は含めず、レポートで件数を示します。

• 文字列リテラルの位置にあり解決できない低信頼の単語も含めず、件数を示します。

• クラスの位置にある未知のトークンなどのエラーがあるとコマンドは失敗します。何も書き込まず、既存の --output ファイルは内容を保つため、パッケージに必要なスタイルが黙ってマニフェストから抜け落ちることはありません。

設定済みの wind.manifests の項目は、このコマンド自身の出力を指すものも含めて、読み込みもコピーもしません。wind.safelist の項目やハイライトのロールクラスも同様です。マニフェストに入るのは走査したソースの候補だけです。--output のパスはソースプランから除外されます。成功すると既存のマニフェストスキーマをアトミックに書き込み、ソースと config が同じなら同じバイト列になります。

{
  "schemaVersion": 1,
  "specVersion": 1,
  "producer": "ui",
  "candidates": ["bg-surface", "group", "p-hsp-sm"]
}

テキストのレポートは標準出力に出ます。内容はプラン、候補とマーカーの件数、除外した件数、各エラーと警告とそのソース位置です。--json を付けると代わりに { "schemaVersion": 1, "command": "manifest", "producer", "output", "written", "coverage", "planDiagnostics", "classification" } を出力します。classification には候補、マーカー、除外した authored クラスと通常の単語とその由来、すべての診断が入ります。マニフェストを書き込まなかった場合は非ゼロで終了します。

マニフェストは、検証に使ったトークンの契約を前提にしています。 分類には選択した config のトークン、ブレークポイント、ダークモードを使います。利用側は各マニフェスト項目を自身の config で厳密に検証するため、それらの候補が使うトークンとブレークポイントをすべて設定する必要があります（たとえば bg-surface には colors の surface）。パッケージの config で通るマニフェストでも、そのトークンを持たない利用側の config で解決できるとは限りません。必要なトークンはパッケージと一緒に文書化するか、プリセットとして配布してください。

zfb preview

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

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

静的モード（アダプタなし、または 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 のバージョン出力形式が変わった場合）。

アダプタモードの preview を停止する

対話型ターミナルでは、zfb がターミナルの制御を wrangler dev に渡すため、Wrangler のホットキーや Ctrl+C は通常どおり使えます。zfb が SIGINT、SIGTERM、または SIGHUP を受け取ると、起動した wrangler dev のプロセスツリー全体（pnpm → node → wrangler → workerd）へそのシグナルを転送します。このツリーは独立したプロセスグループで動作します。zfb は停止を最大 5 秒待ち、まだ動いているプロセスを強制終了します。これにより preview の --port が解放されます。

シグナルを受けた zfb はエラーバナーを出さずに 128 + シグナル番号 で終了します。SIGINT なら 130、SIGTERM なら 143、SIGHUP なら 129 です。一方、wrangler dev が自ら失敗した場合は wrangler dev exited with status … と報告し、終了ステータス 1 で終了します。

zfb に送られた SIGKILL は捕捉できないため、その場合 zfb はプロセスツリーを後片付けできません。また、シグナルを転送しない外側のラッパー（例: pnpm exec zfb preview … の PID）だけを停止しても、シグナルは zfb に届きません。スクリプトからは zfb のプロセス自体を停止してください。Windows ではプロセスツリーの後片付けはまだ実装されていません。

フラグ

* 次の順にフォールバックします: 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] [--scratch-dir <path>] [--define <KEY=EXPR>]...

このコマンドは TypeScript、コレクションスキーマ、SSR ルートを検査し、JSX pragma の警告も報告します。

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

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

TypeScript の検査ではプロジェクトの tsconfig.json を使うため、通常の zfb check にはこのファイルが必要です。--skip-tsc を指定すると、このファイルがなくてもほかのチェックを実行できます。

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

ZB005 の警告は、pages/ 外のコンポーネントも含め、プロジェクト内の authored .tsx / .jsx を調べます。依存パッケージ、生成出力、スクラッチディレクトリ、シンボリックリンクは除外します。--skip-tsc でも実行され、この警告だけでは check は失敗しません。ルートがある場合は SSR ルート契約も調べ、強い検出は失敗、推測的な検出は警告になります。

フラグ

例

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

# tsc なしで検査
zfb check --skip-tsc

スクラッチディレクトリ

デフォルトでは、どのコマンドもプロジェクト内の決まった場所に生成物を書き込みます。バンドルや dev 用のファイルは <root>/.zfb-build/ の下に、dev サーバーの依存グラフは <root>/.zfb/graph.bin に置かれます。そのため、同じチェックアウトで 2 つのコマンドを同時に実行すると、これらのファイルを共有してしまいます。たとえば zfb build が、実行中の zfb dev が配信しているバンドルを上書きしたり、2 つの dev サーバーが互いのバンドルや永続化された依存グラフを上書きしたりします。--scratch-dir <PATH> を指定すると、その呼び出し専用のディレクトリにこれらの生成物を置くため、同時に実行するコマンド同士が干渉しません。同時に実行するコマンドには、それぞれ 別のスクラッチディレクトリを指定してください。

# 同じチェックアウトで 2 つの dev サーバーと 1 つのビルドを、それぞれ専用のスクラッチディレクトリで実行する
zfb dev --port 3000 --scratch-dir .zfb-build/dev-main
zfb dev --port 3001 --scratch-dir .zfb-build/dev-preview
zfb build --scratch-dir .zfb-build/build

# 環境変数で指定する場合
ZFB_SCRATCH_DIR=.zfb-build/dev-preview zfb dev --port 3001

スクラッチディレクトリの指定

• --scratch-dir は zfb dev、zfb build、zfb check、zfb preview で使えます。

• フラグは環境変数 ZFB_SCRATCH_DIR より優先されます。空文字列や空白だけの ZFB_SCRATCH_DIR は未設定として扱われます。

• 相対パスは現在の作業ディレクトリ、つまりプロジェクトルートを基準に解決されます。ディレクトリが存在しなければ zfb が作成しますが、作成するのはパスが後述のルールをすべて満たした場合だけです。

• フラグも環境変数も指定しない場合、zfb はこれまでどおりデフォルトの <root>/.zfb-build/ レイアウトを使います。ロックは取らず、余分なものも作成しません。

置き場所

推奨する置き場所は <root>/.zfb-build/<name> です。スキャフォールドのテンプレートは .zfb-build/ をすでに gitignore しており、zfb がソースを走査する処理もすべてこのディレクトリをスキップします。

プロジェクト内に置く場合、スクラッチディレクトリは .zfb-build/ の 配下（.zfb-build そのものは不可）でなければなりません。それ以外のプロジェクト内の場所は拒否されます。/tmp/zfb-dev-main のようなプロジェクト外の場所は、同じルールを満たす限り使えます。

次の場所はいずれもエラーになります。エラーメッセージには、該当するルールのタグと関係するパスが表示されます。

zfb はシンボリックリンクを解決したうえでパスを比較するため、シンボリックリンクの別名でルールをすり抜けることはできません。ルールはディレクトリの作成前に一度、作成後のディレクトリに対してもう一度チェックされます。一方、R6 の逆、つまり既存のスクラッチディレクトリを内側に含むディレクトリを新たにスクラッチディレクトリにするケースは検出 しません。スクラッチディレクトリはネストさせず、.zfb-build/dev-main と .zfb-build/build のように兄弟として並べてください。

所有権とロック

コマンドは実行中、<scratch>/.zfb-scratch.lock に排他ロックを保持します。

• 同じディレクトリを使う 2 つ目のコマンドは即座に失敗します。 スクラッチディレクトリが別の zfb プロセスで使用中である旨のエラーで終了します。ロックの解放を待つことも、ディレクトリを共有することもありません。

• ロックファイルは、そのディレクトリが zfb のものである目印にもなります。 このファイルがあるディレクトリは、後のコマンドで再利用できます。空のディレクトリも使えます。ロックファイルのない空でないディレクトリは拒否されるため、--scratch-dir ~/Documents のようなタイプミスでビルド成果物が自分のファイルに書き込まれることはありません。

• ロックにはローカルファイルシステムが必要です。 アドバイザリロックに対応していないファイルシステムでは、排他性なしで続行するのではなく、コマンドが失敗します。

中に置かれるもの

zfb check と zfb preview は、スクラッチディレクトリに zfb 自身のファイルを何も書き込みません。検証してロックするだけです。ただし zfb preview で動くプラグインも ctx.scratchDir を受け取るため、そこに書き込むことはあります。

スクラッチディレクトリを使う zfb dev はビルド済みの出力ディレクトリを読まない

スクラッチディレクトリを使う zfb dev は、出力ディレクトリを一切読みません。以前の zfb build が別の define や別の状態でビルドしたものかもしれないため、dev はそれを信用しません。

• ルートが最初にレンダリングされる前に、ビルド済みの HTML を配信しません。

• /assets/* を出力ディレクトリにフォールバックしません。

• boot-lazy のシードとしても使わないため、ZFB_DEV_BOOT_LAZY=1 は即時起動のレンダリングに戻ります。

dev はその旨を 1 行の info ログで出力します。

scratch dir in use (<scratch>): ignoring prebuilt <outDir> — no dist/ fallback for HTML or /assets

スクラッチディレクトリを使わない場合、dev の挙動はこれまでと変わりません。

意図的に共有されるもの

スクラッチディレクトリが分離するのは、zfb 自身の生成物です。次のものは、設計上、同時に実行するコマンドの間で共有されたままです。

• 出力ディレクトリ。 同じ出力ディレクトリを使う 2 つの zfb build は、互いに上書きし合います。それぞれに別の --outdir を指定してください。

• もともとプロセスごとに分かれている一時ファイル。 プロジェクトルートに置かれる esbuild のエントリ、tsconfig、仮想モジュールの一時ファイル、shadow セッション、設定ローダーの一時ディレクトリは、プロセスごとに一意の名前が付くため衝突しません。

• ユーザーの tsconfig が出力する .tsbuildinfo。 tsconfig で incremental や composite を有効にしている場合、zfb check は設定を変えずに tsc を実行するため、tsc は tsconfig の指定どおりの場所にこのファイルを書き込みます。

• .zfb/ ステージングディレクトリ。 プロジェクトのコードがここからインポートするため、移動できません。

• プラグインが独自に持つディレクトリ。 プロジェクトルートにある自前のディレクトリ（たとえば .zudo-doc/）に書き込むプラグインは、同時に実行するコマンドの間でそれを共有したままです。プラグインまで分離するには、プラグイン側が ctx.scratchDir を使うように対応する必要があります。プラグイン を参照してください。

呼び出し単位の define

--define KEY=EXPR は、config の bundle.define に加えて、その呼び出しに限った esbuild の define 置換を追加します。zfb.config.ts を書き換えずに、同じチェックアウトを別の値でビルドしたり配信したりするときに使います。環境ごとにオリジンを変える場合などです。

zfb build --define __ORIGIN__='"https://www.example.com"'
zfb dev --scratch-dir .zfb-build/dev-preview \
  --define __ORIGIN__='"https://preview.example.com"' \
  --define __FEATURE_X__=true

• 対応コマンド。 --define は複数回指定でき、zfb dev、zfb build、zfb check で使えます。zfb preview はビルド済みの出力を配信するだけで何もバンドルしないため、このフラグを受け付けません。

• 値は esbuild の生の式です。 bundle.define とまったく同じ扱いなので、文字列には内側の引用符が必要です: --define __ORIGIN__='"https://a.example"'。外側のシングルクォートで、シェルに内側のダブルクォートを残させます。フラグは最初の = で分割されるため、式の中に = を含めても構いません。

• マージ。 CLI の値は bundle.define にキー単位でマージされ、同じキーでは CLI が優先されます。同じキーを繰り返し指定した場合は最後の指定が勝つため、スクリプトで共通の引数リストの末尾に上書きを追加できます。プラグインは、マージ後のマップを ctx.config.bundle.define で参照できます。

• エラー。 = がない値、空のキー、空の式は、CLI の使い方エラーになります。予約済みのキー（import.meta.env.PROD、import.meta.env.DEV、process.env.NODE_ENV）も同様です。それ以上のキーの構文は zfb では検査しません。不正なキーは、bundle.define と同じくバンドル時に esbuild が報告します。

• セキュリティ。 bundle.define の警告はここにも当てはまります。どの値もブラウザ向けのバンドルに含まれるため、秘密情報は絶対に渡さないでください。

zfb check での --define

zfb check は --define の値を検証してマージしますが、その値は使いません。define という概念を持たない tsc には渡りません。グローバル変数の型は、tsconfig が含める .d.ts ファイルで宣言してください。

// components/zfb-env.d.ts
declare const __ORIGIN__: string;

check でもこのフラグを受け付けるのは、1 つの引数リストを dev、build、check で使い回せるようにするためです。また、不正な値は check の段階で失敗するため、check を通過して後のビルドで失敗することがありません。

define はビルドの同一性の一部

有効な define のマップは、zfb がサーバーレンダリングした island のマークアップと island のバンドルに刻み込む、ビルドの同一性の一部です。異なる define でビルドされた SSR 出力と island が互いにハイドレーションすることはありません。同一性が一致しない island は、誤った値のまま黙ってハイドレーションするのではなく、ZR_IDENTITY エラーで失敗します。

この同一性にはプロジェクトのソースファイルも含まれます。ただし、プロジェクト自身の .gitignore に一致するファイル、隠しディレクトリ、ビルドやスクラッチの出力は除外されます。.zudo-doc/routes-src など、zfb が使う既知の内部ステージングパスは、隠されていたり gitignore されていたりしても含まれます。リンクされたローカルパッケージ、プラグインのエイリアス、tsconfig の paths の対象、仮想モジュール、有効な define のマップも同一性に反映されます。リンクされたパッケージには、そのパッケージ自身の .gitignore と、ワークスペースルートまでの上位の .gitignore の規則を適用します。パッケージがワークスペース外にある場合は、最も近い Git ルートまでを対象にします。どちらもない場合は、そのパッケージ自身を境界とします。走査では隠しエントリを除外します。exports、main、module、imports で宣言されたパッケージのエントリファイルとディレクトリ（たとえば dist/）は、gitignore されていても含まれます。宣言されたエントリファイルから相対 import で到達するファイルも含まれます。具体的なエイリアスと tsconfig の対象ファイル、およびそれらから相対 import で到達するファイルは、gitignore されていたり隠されていたりしても含まれます。リンクされたパッケージ内のファイルが gitignore され、宣言されたエントリでも、これらの相対 import で到達するファイルでもなければ、同一性には含まれません。これは対象ファイルを選ぶ規則であり、実際に到達可能なモジュールグラフを厳密に求めるものではありません。プロジェクト内のファイルは、コードが直接 import していても gitignore されていれば同一性には含まれません。そのような生成入力は .gitignore の対象から外して Git で管理するか、決定的に再生成してください。

チェックアウト先のパスとスクラッチディレクトリの場所は、同一性にも出力されるバンドルにも影響しません。同じコミット、ロックファイル、ビルドオプションなら、ローカルと CI の dist/ はバイト単位で一致します。test-results/ のようなツールの出力は、宣言されたエントリや対象ファイルからの相対 import の外にあり、gitignore されていれば、同一性とバンドルのバイト列を変えません。適用される ignore 規則がなければ、同一性の入力に残ります。zfb dev では、gitignore されたファイルへの書き込みでも watcher の tick が起こり得ますが、同一性は変わりません。watcher 側のフィルタリングは #3926 で扱います。

環境変数

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