はじめに

zfb とは何か、誰のためのものか、動かし方は 3 つあること、そしてそのコンセプトが Astro や Next.js とどう対応するか。

日々のフロントエンド開発のほとんどを 1 つの CLI で。zfb は作成、開発、型とコンテンツのチェック、ビルド、プレビューをまとめます。TSX、MDX、Markdown、HTML のページに、zudo-wind の CSS と zudo-react のインタラクションを必要に応じて加えます。小さく組み合わせやすいエンジンとして、静的サイト、Workers、ローカルアプリを支えます。

最初のサイトで始め、zfb で作るから日々の作業を探してください。

誰のためのものか

ドキュメントサイト、ブログ、コンテンツを組み込むアプリを、小さな API で構築したい人に向いています。設計の背景は設計哲学、配信先の選択はデプロイと組み込みを参照してください。

zfb が提供するもの

「なぜこの形なのか」（狭いスコープ、プラグインよりレシピ、ミドルウェア層なし）という観点については Design philosophy を参照してください。

組み込み V8 ワーカー — ページは Rust に組み込まれた V8 ランタイムを通じてレンダリングされます。ビルド時に別途 Node プロセスを起動する必要はありません。
アトミックな書き出し — 生成ファイルはファイル単位でアトミックに書き込まれるため、読み手が半分だけ書かれた HTML ファイルを観測することはありません。zfb build は書き込みを始める前に出力ディレクトリを消去するため、失敗したビルドが以前の dist/ を完全なまま残す保証はありません。
ページ単位のインクリメンタルリビルド — 共有レイアウトを変更すると、それを import しているページだけが対象になり、サイト全体には及びません。大規模サイトでも開発ループのレイテンシは数十ミリ秒に保たれます。
オプトイン方式の島 — "use client" は export を島のターゲットとして利用可能にします。島を有効にするには到達可能な <Island> 境界が必要です。島のないページでも独立したクライアントスクリプトを読み込めます。
フロントマターとコンテンツコレクション — 名前付きディレクトリに置いた Markdown・MDX・TypeScript データファイルは型付きのコレクションになり、ページから getCollection() でクエリできます。
動的ルート — pages/blog/[slug].tsx は paths() 関数をエクスポートします。zfb はビルド時にこれを評価し、ルートを slug ごとに 1 つの HTML ファイルへ展開します。
MDX コンポーネント — 任意の TSX コンポーネントを .mdx コンテンツに import し、JSX として使えます。
HTML 以外のページ — ページファイルは contentType をエクスポートすることで、HTML の代わりに JSON・XML・RSS など任意のテキスト形式を生成できます。
コンテンツクエリのブリッジ — getCollection() はページコンポーネントだけでなく、MDX ファイル内や paths() 内でも利用できます。
単一バイナリの配布 — zfb は 1 つの Rust バイナリとして提供されます。フレームワーク自体に node_modules は不要で、監査すべきプラグインレジストリもありません。

Astro から見て馴染みのある点

Astro から来た人には、コンセプトは次のように対応します。

Astro のコンセプト	zfb での対応
`src/pages/` のファイルシステムルーティング	`pages/` ディレクトリ、同じ命名規約
フロントマターフェンスを持つ `.astro` コンポーネント	`getStaticProps` をエクスポートする TSX ページファイル
型付きスキーマを持つ Content Collections	`getCollection()` + `zfb.config.ts` で宣言するスキーマ
レイアウト内の `<slot />`	`children` prop — 素の TSX 合成
`client:load` ディレクティブ	`"use client"` ターゲットと到達可能な `<Island>` 境界
静的アセット用の `public/`	`public/` — 同じセマンティクス
`astro.config.mjs`	`zfb.config.ts`（TypeScript、直接ロード）

コンポーネントには zfb 独自の JSX ランタイムである zudo-react と TSX を使います。React や Preact の差し替え互換ではありません。ページは Markdown、MDX、HTML にも対応します。Markdown と HTML ページを参照してください。

Next.js から見て馴染みのある点

Next.js から来た人には、コンセプトは次のように対応します。

Next.js のコンセプト	zfb での対応
`pages/` ディレクトリルーティング（Pages Router）	`pages/` — 同じファイル命名とネストのルール
`getStaticProps` / `getStaticPaths`	`getStaticProps` + `paths()` エクスポート、同じ 2 関数パターン
動的ルート `[slug].tsx`	`[slug].tsx` — 同一の構文
キャッチオールルート `[...slug].tsx`	`[...slug].tsx` — 同一の構文
静的アセット用の `public/`	`public/` — 同じセマンティクス
ページをラップするレイアウトコンポーネント	ページをラップするレイアウトコンポーネント — 素の TSX 合成

異なる点: zfb は デフォルトで SSG です。すべてのページはビルド時に計算され、静的 HTML になります。本当にリクエスト時の挙動を必要とするルートは prerender = false でオプトアウトし、設定済みのアダプター（例: @takazudo/zfb-adapter-cloudflare 経由の Cloudflare Workers Static Assets）が処理します。Cloudflare Workers 上の SSR は、明示された制約を伴うサポートされた形です。アダプターは Cloudflare 向けの 1 つだけであり、App Router も、React Server Components も、ミドルウェア層も、自動 ISR もありません。デフォルトは静的ビルドのままです。

クライアントルーターと View Transitions

@takazudo/zfb-runtime パッケージは <ClientRouter /> コンポーネントを提供します。これは同一オリジンへのナビゲーションをインターセプトし、フルリロードなしでページコンテンツを差し替えます。オプションで View Transitions API もサポートします。ルートレイアウトにマウントしてオプトインしてください。マウントしないページは通常のリンク挙動になります。

マイグレーションガイド

Migrating from Astro — 既存の Astro 静的サイトを zfb へ移行するための、コンセプトごとの対応表。

次に読むもの

Installation では CLI のビルドとインストールを扱います。 Your first site では、プロジェクトのスキャフォールドからビルドまでを一通り解説します。