zfb を選ぶ

zfb がプロジェクトに合うのはどんなときか、合わないのはどんなときか、そしてスケールのスイートスポットはどこか。

zfb は焦点を絞ったツールです。特定の問題をうまく解決し、それ以外の問題は意図的に他の ツールに委ねます。このページではそれを整理し、時間を投資する前に判断できるようにします。

zfb がよく合うとき

以下の多くがあなたのプロジェクトに当てはまるなら、zfb は強くマッチします。

コンテンツ中心の、静的生成サイト。 真実の源はリポジトリ内の Markdown または MDX ファイルです。それらのファイルを静的 HTML に変えるビルドステップが欲しく、そのビルドが 高速で決定的であってほしい。zfb のアーキテクチャ全体はこのケースを軸に形作られています。

ページ単位の依存グラフ。 数百のページがあり、編集のたびにフルリビルドはしたくない。 zfb は各ページがどのソースファイルに依存しているかを追跡し、何かが変わったときに影響を 受けるページだけをリビルドします。依存グラフ（crates/zfb-graph）は後付けではなく、 エンジンの第一級の構成要素です。

workerd の形をした出力バンドル。 ターゲットが Cloudflare Workers または Pages。 zfb のビルド時 JS ホストは V8 ベース（組み込み V8 経由）で、workerd と同じエンジン ファミリーです。コンテンツスナップショットとアイランドバンドルはその環境向けのサイズに 収まっています。Workers にデプロイするなら、実際にフィットするバンドルの形が得られます。

Cloudflare Pages に優しいデプロイ。 zfb build の静的出力は、Pages デプロイに そのまま投入できます。管理すべきサーバーランタイムも、設定すべきサーバーレス関数も、 アダプタ層もありません。ビルドされた dist/ がデプロイの成果物そのものです。

軽量なインタラクティブアイランド。 ページはほとんどが静的なドキュメントで、少数の インタラクティブなコンポーネント（検索ボックス、カウンター、モーダルのトリガーなど）が あるだけ。zfb のアイランドモデル（"use client"）は、各ページが使うアイランドの JS を ちょうどそれだけ配信し、それ以外は何も配信しません。アイランドのないページが配信する クライアント JS は 0 バイトです。

比較

最も意味のある違いは ビルド時 JS ホスト です。zfb は組み込み V8 を直接使います。 Cloudflare の workerd と同じエンジンファミリーです。Astro と Next.js はどちらもフルの Node.js プロセスでビルドします。Workers をターゲットにしたデプロイでは、zfb のホストは ターゲットランタイムに近く、グローバルの可用性やモジュール解決まわりでの驚きが少なくなります。

別のものを選ぶとき

zfb が誤った選択になるケースはいくつかあります。コミットする前に自分自身に正直になりましょう。

サイトのほとんど、またはすべてのページが動的。 zfb はデフォルトで SSG です。すべての ページはビルド時に静的 HTML へ計算されます。リクエスト時の振る舞いが必要なルートは prerender = false でオプトアウトでき、アダプタによって配信されます（SSR and Cloudflare bindings を参照）。これは、それ以外は静的なサイト上の わずかな動的ルートをカバーします。もし すべて のページが動的（ユーザーごと、リクエスト ごと）なら、zfb は誤ったツールであり、フルの SSR フレームワークが正しい選択です。

幅広いマルチフレームワークサポートが必要。 Astro のアダプタエコシステムは、同じサイトの 中で React・Vue・Svelte・Solid などを切り替えられます。zfb のクライアント側は TSX （React または Preact）です。チームが複数のフレームワークのコンポーネントを抱えていて、 それらをすべて 1 つのサイトに収めたいなら、zfb は適切なホストではありません。

ページが 100,000 以上ある。 zfb はインメモリのコンテンツスナップショットを構築し、 レンダーパスのあいだ V8 ホストに埋め込みます。数百から数千の MDX ファイルなら、デフォルトの workerd メモリに余裕で収まります。非常に大規模なコーパス（数万のエントリ、または数メガバイトの 本文を持つエントリ）では、V8 の RSS がスナップショットのサイズに比例して線形に増えます。 その規模では、スナップショットの設計を見直す必要があり（下記の スケールのスイートスポット セクションを参照）、zfb は今日その問題を解決しません。

実績があり、広く採用され、大きなエコシステムを持つツールが欲しい。 zfb は焦点を絞った、意見の強いエンジンです。大きなコミュニティ、豊富なプラグインエコシステム、あるいは今日すぐに使える実戦投入済みの本番スケールが必要なら、Astro が正しい答えです。

スケールのスイートスポット

このエンジンは 数百から数千の MDX ページ 向けに設計されています。それがカバーするのは:

• 典型的なドキュメントサイト（50〜500 ページ）
• 数年分のアーカイブを持つ開発者ブログ（100〜2000 記事）
• zudo-doc 規模のコンテンツセット

そのサイズではコンテンツスナップショットは小さく、コールドスタートのビルド時間は秒単位で 測られ、依存グラフは総ページ数に関係なくインクリメンタルリビルドを高速に保ちます。

おおよそ 10,000 ページを超えると、インメモリのスナップショットアプローチがボトルネックに なります。その規模での正しい答えは、より大きなモノリスを作ることではありません。コンテンツを 複数の zfb プロジェクトにシャーディングし（セクションごと、ロケールごと、コンテンツタイプ ごとに 1 つ）、CDN 層でそれらを合成することです。その合成のストーリーはロードマップにありますが、 今日は実装されていません。

ビルドの実際のスナップショットのフットプリントを調べるには:

ZFB_DEBUG_SNAPSHOT=1 pnpm exec zfb build

これは stderr に 1 行だけ出力します。

content snapshot: 187 entries / 412 KB

ここでの KB は決定的な JSON シリアライズのバイトサイズであり、V8 ヒープコストの信頼できる 代理指標です。コンテンツが増えるにつれてこの数値を見守ってください。数百メガバイトを超えて 登っていくなら、スイートスポットの端に近づいています。メモリモデルの完全な説明は README scaling note にあります。

次に行く先

• Getting started — 最初のサイトをスキャフォールドします。
• Design philosophy — 「意図的に狭く」というスタンスと、この一連のトレードオフを説明する「プラグインよりレシピ」というフレーミング。
• Architecture: Build engine — Rust クレート、JS ホスト、スナップショットがどう組み合わさるのか。
• Engine vs Framework — zfb がコミットする 6 つのプリミティブと、エンジンの外側にあるもの。