zfb を選ぶ

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

このページで扱う内容

zfb があなたのプロジェクトに適したツールかどうか — zfb が得意でないことについての率直な見解も含みます。アーキテクチャ概要、getting-started ガイド、そしてREADME のスケールに関する注記と相互リンクしています。

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

zfb がよく合うとき

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

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

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

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

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

軽量なインタラクティブアイランド。 ページはほとんどが静的なドキュメントで、少数のインタラクティブなコンポーネント（検索ボックス、カウンター、モーダルのトリガーなど）があるだけ。zfb のアイランドモデル（"use client"）は、プロジェクト用の単一の共有 islands バンドルを配信し、それを島マーカーを含むページにだけ注入します。島を 1 つ持つページは、プロジェクト内の他の島のコードもダウンロードする場合があります。島のないページは islands スクリプトをスキップしますが、他の client-script 経路が JavaScript を配信することはあります。

比較

	zfb	Astro	Next.js
CLI 言語	Rust	Node.js	Node.js
TSX コンパイル	SWC（組み込み）	Vite/Rollup	SWC/Webpack
バンドラ	esbuild（アイランド）	Vite	Webpack/Turbopack
ビルド時 JS ホスト	組み込み V8	Node.js	Node.js
クライアントフレームワーク	任意の TSX（`"use client"`）	任意（アダプタ）	React

最も意味のある違いは ビルド時 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 つのプリミティブと、エンジンの外側にあるもの。