zfb を選ぶ
zfb は誰のためのものか、3 つの実行形態（静的ビルド、Cloudflare Workers 上の SSR、ローカルコンテンツサーバー）が実際のプロジェクトにどう対応するか、そしてスケールのスイートスポットはどこか。
このページで扱う内容
zfb があなたのプロジェクトに適したツールかどうか — zfb が得意でないことについての 率直な見解も含みます。zfb を動かす 3 つの方法、アーキテクチャ概要、getting-started ガイド、そしてREADME のスケールに関する 注記と相互リンクしています。
zfb は焦点を絞ったツールです。特定の問題をうまく解決し、それ以外の問題は意図的に他の ツールに委ねます。このページではそれを整理し、時間を投資する前に判断できるようにします。
誰のためのものか
zfb は 1 人の開発者が、自分の作っているもののために作っているツールです。作っている ものとは、zudo-doc のドキュメントサイト、CCResDoc、 そしてそれらが配信するサイトです。公開しているのは、同じように考える人が欲しがるかもしれないから です。CCResDoc がやっているように Tauri のようなアプリにコンテンツエンジンを組み込み たい人、そしてサイト全体を支配するフレームワークではなく、SSG と SSR を小さく合成可能な 部品として使いたい人に向いています。
出発点は素朴なものでした。プロジェクトを始めた当時、何もかもが大きく感じられました。 Next.js は大きい。Astro はもっと軽量ですが、このプロジェクトには必要のない外部 ライブラリの大きなエコシステムをサポートしています。今日では小さな機能の多くを AI の支援で すばやく高い品質で作れるので、ライブラリがその 1 つひとつに対するデフォルトの答えでは なくなりました。「必要ない」と言い切るのは言い過ぎですが、そうした部品は他人の リリーススケジュールの下に置くより、自分の管理下に置いたほうが良いのです。小さな コア CLI はその考えに合っていました。プラグインよりレシピを選ぶ議論の全体は Design philosophy にあります。
ですからこのページは、Astro や Next.js からあなたを引き剥がそうとするものではありません。 どちらかがあなたのプロジェクトに合うなら、それを使ってください。zfb は、本当に面白い部分が ページのレンダリング以外の場所にあるプロジェクトのためのものです。
zfb がよく合うとき
zfb は同じ Request/Response アプリケーションを 3 つの形で動かします。多くの プロジェクトはそのうちの 1 つに寄ります。3 つすべての詳細は zfb を動かす 3 つの方法 で扱います。このセクションは、 それぞれが合うかどうかを見極めるためのものです。
静的ビルド
真実の源がリポジトリ内の Markdown または MDX ファイルであり、それらを静的 HTML に 変える高速で決定的なビルドステップが欲しいときに強くマッチします。zfb の アーキテクチャ全体はこのケースを軸に形作られています。
ページ単位の依存グラフ。 数百のページがあるなら、編集のたびにフルリビルドは したくないはずです。zfb は各ページがどのソースファイルに依存しているかを追跡し、 何かが変わったときに影響を受けるページだけをリビルドします。依存グラフ （crates/zfb-graph）は後付けではなく、エンジンの第一級の構成要素です。
Workers Static Assets へのドロップイン。 zfb build の静的出力は、Workers Static Assets デプロイ（Pages 互換）にそのまま投入できます。管理すべきサーバー ランタイムも、設定すべきサーバーレス関数も、アダプター層もありません。ビルドされた dist/ がデプロイの成果物そのものです。
Cloudflare Workers 上の SSR
一部のルートをリクエスト時に実行する必要があり、ターゲットが Cloudflare Workers で あるときに強くマッチします。prerender = false でプリレンダリングをオプトアウトした ルートは @takazudo/zfb-adapter-cloudflare が配信し、Cloudflare のバインディングは prop-drilling なしに getCloudflareContext() から任意のページコンポーネントに届きます。
2 つの形のあいだでバンドルの契約は変わりません。ビルドが組み込み V8 アイソレートの 中で駆動するワーカーバンドルは、動的ルートのために Workers へデプロイされるものと 同じ形です。メンタルモデルは Worker 上の SSR、実際の セットアップは SSR and Cloudflare bindings ガイド にあります。このモデルは Workers Static Assets 上で検証されています。Cloudflare Pages のアドバンストモードはこのアダプターについて未検証です。
ローカルコンテンツサーバー
別のプログラムがウィンドウを持ち、zfb がコンテンツを持つときに強くマッチします。 zfb dev はそのプログラムによってループバックポート上に子プロセスとして起動され、 その WebView からのリクエストに応答します。plugins: [] を指定した標準の組み込み V8 ビルドでは Node のプラグインホストは起動しないため、動作中のサーバーはマシン上に Node.js を必要と しません。サーバーが動いているあいだ、他のプロセスがコンテンツツリーへ MDX を書き込み、 content-watch の HMR がリビルドなしにその変更を拾います。
CCResDoc がその証拠です。Tauri のホストが ネイティブの zfb バイナリを、設定で選ばれたループバックポート上の子プロセスとして 起動し、Rust のジェネレーターとウォッチャーが設定済みの Claude と Codex の リソースディレクトリから MDX を出力し、ホストは実際のページをポーリングして、 レスポンスが期待するシェルを含むまでサーバーを準備完了とみなしません。子プロセスとして 起動したサーバーと、インプロセスの zfb-server クレート との 組み合わせのマトリクスは Desktop deployment を 参照してください。
軽量なインタラクティブアイランド
これは 4 つ目の形ではなく、3 つの形すべてに共通する性質です。zfb は、ほとんどが 静的なドキュメントでありながら少数のインタラクティブなコンポーネント（検索ボックス、 カウンター、モーダルのトリガーなど）を持つページに向いています。アイランドモデル （"use client"）は、プロジェクト用の単一の共有 islands バンドルを配信し、それを島 マーカーを含むページにだけ注入します。島を 1 つ持つページは、プロジェクト内の他の島の コードもダウンロードする場合があります。島のないページは islands スクリプトを スキップしますが、他の client-script 経路が JavaScript を配信することはあります。
zfb はどこに位置するか
zfb はコンテンツサイトの 1 つの層であって、その全体ではありません。スタックを上から 読むとこうなります。
| 層 | そこにあるもの |
|---|---|
| フレームワーク / サイト体験 | Astro、Next.js、VitePress、Starlight、zudo-doc |
| サイトエンジン | zfb — ルーティング、SSG、SSR、アイランド、コレクション |
| コンテンツパイプライン | remark/rehype、markdown-it、zfb 自身の MDX パイプライン |
| パーサー / コンパイラ / ランタイム | Rust、SWC、Rolldown、esbuild、V8 |
Astro と Next.js はサイト体験を所有します。サイドバー、テーマ、ブログの慣習、サイトの 完成した形です。zfb はその下の層を所有します。zudo-doc のようなフレームワークが載る エンジンであり、CCResDoc のようなアプリケーションが載るエンジンです。プロジェクトの 難しい部分がページのレンダリング以外の場所にあり、レンダリング層は小さく、予測可能で、 自分で組み合わせられるものであってほしいなら zfb を選んでください。難しい部分が サイト体験 そのもの なら、フレームワークのほうが速くたどり着けます。
技術的な違いを 1 つ挙げておく価値があります。zfb のビルド時 JS ホストは組み込み V8 で、 Cloudflare の workerd と同じエンジンファミリーです。一方 Astro と Next.js はフルの Node.js プロセスでビルドします。つまり Workers をターゲットにしたデプロイでは、zfb の ビルドホストはターゲットランタイムに近いということです。
別のものを選ぶとき
zfb が誤った選択になるケースはいくつかあります。コミットする前に自分自身に正直に なりましょう。
Cloudflare アダプターが提供する以上の SSR が必要。 SSR は後付けではなく サポートされた形ですが、アダプターは Cloudflare Workers 向けの 1 つだけです。ISR も、 React Server Components も、ミドルウェア層も、Node・Vercel・Deno のアダプターも ありません。リクエスト時の要件がそれらのどれかを必要とするなら、フルの SSR フレームワークが正しいツールです。
幅広いマルチフレームワークサポートが必要。 Astro のアダプターエコシステムは、 同じサイトの中で React・Vue・Svelte・Solid などを切り替えられます。zfb のクライアント 側は独自の zudo-react ランタイムを使う TSX であり、これらのフレームワーク用に書かれたコンポーネントとの相互運用は提供しません。チームが複数のフレームワークのコンポーネントを 抱えていて、それらをすべて 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 にあります。
次に行く先
zfb を動かす 3 つの方法 — 静的ビルド、Worker、ローカルコンテンツサーバーを並べて比較します。
Getting started — 最初のサイトをスキャフォールドします。
Design philosophy — 「意図的に狭く」というスタンスと、この一連のトレードオフを説明する「プラグインよりレシピ」というフレーミング。
Architecture: Build engine — Rust クレート、JS ホスト、スナップショットがどう組み合わさるのか。
Engine vs Framework — zfb が提供する公開 APIと、エンジンの外側にあるもの。