最初のサイト

zfb プロジェクトをおよそ 5 分でスキャフォールド・実行・ビルドする。

このウォークスルーでは、空のディレクトリから開発サーバーの起動、そしてサイトのビルドまでを案内します。グローバルな CLI インストールは不要です。スキャフォールドコマンドが必要なものをすべてオンデマンドで取得します。

新しいプロジェクトをスキャフォールドする

pnpm create zfb@latest my-site
# または
npm create zfb@latest my-site

実行する前に出力を見る

create-zfb.takazudomodular.com では、このコマンドが生成するものをそのまま公開しています。basic-blog テンプレートをmain への push ごとにビルドしてデプロイしたものです。サイトの内容は一切手書きしていません。すべてのプルリクエストを通すのと同じクリーンルーム実行によって CI で生成されるため、これから手元に入るテンプレートとずれることがありません。

pnpm 11 に関する注意

pnpm 11 の minimumReleaseAge により、新しいリリースから約 48 時間以内はcreate-zfb の一つ前のリリースがインストールされることがあります。create-zfb が起動時に古いインストールについて警告する場合は、pnpm create zfb@latest --config.minimumReleaseAge=0 で再実行するか、代わりに npm create zfb@latest を使ってください。

これは create-zfb イニシャライザを実行します。内部では zfb new を呼び出し、同梱の basic-blog テンプレートを my-site/ にコピーします。PATH 上に pnpm があれば、zfb はテンプレートのコピー直後に pnpm install を自動実行します。なければ、自分で実行するよう促す短いメッセージを表示します。

cd my-site

zfb CLI をすでにグローバルインストールしている場合（Installation を参照）、zfb new を直接呼び出しても同じ結果が得られます。

zfb new my-site --template basic-blog

--template basic-blog はデフォルトなので、省略できます。Node.js 依存を一切必要としないプロジェクト向けに node-free テンプレートも利用できます。package.json を同梱せず、.tsx に加えて .md/.html のページエントリを使います。このページの書き方については Markdown and HTML Pages を参照してください。

basic-blog がスキャフォールドするのは、zfb.config.ts（JSON ではありません）、3 つのシード記事を持つ blog コンテンツコレクション、4 つのルート、そして 1 つのクライアント島です。同梱の README.md がツリーの案内になっており、プロジェクト構造が同じ範囲をより詳しく扱います。

開発サーバーを起動する

pnpm zfb dev
# または
npx zfb dev

ホストとポートを示す「ready」バナーが表示されます（デフォルトは http://localhost:3000）。zfb は固定された一連のプロジェクトルートを監視します。pages/・content/・components/・layouts/・styles/・data/・src/ と、2 つの設定ファイル（zfb.config.json、zfb.config.ts）です。これに加えて、設定でコレクションの path 値や絶対パスの extraWatchPaths エントリとして宣言された任意のパスも監視します。デフォルトの public/ ディレクトリは監視されません。これらのファイルはディスクから直接配信されます。監視対象のファイルを保存すると、接続中のブラウザにライブリロードがブロードキャストされます。

ホストとポートは CLI から上書きできます。これらは常に zfb.config.ts より優先されます。

pnpm zfb dev --port 4000 --host 0.0.0.0
# または
npx zfb dev --port 4000 --host 0.0.0.0

ビルドとプレビュー

サイトの静的ビルドを生成するには:

pnpm zfb build
pnpm zfb preview
# または
npx zfb build
npx zfb preview

zfb build は CLI の --outdir → config の outDir → 組み込みデフォルトの dist/ という順で選んだディレクトリへ書き出し、ファイルシステムルーターでルートを列挙し、静的ルートごとに 1 つの HTML ファイルを書き出します。build コマンドはサーバーを起動しないため、--port フラグはありません。

zfb preview も同じ出力ディレクトリの優先順位を使い、選択されたディレクトリを HTTP で配信します。preview の --port フラグは設定の port より優先されます。どちらも設定されていない場合、preview は組み込みデフォルトの 4321 を使います。

3 つのコマンドはすべて zfb.config.* の outDir を尊重します。build と preview では、明示的な --outdir が常に設定値より優先されます。

プロジェクトを型チェックする

pnpm typecheck
# または
npx zfb check

zfb check は 1 回の実行で 2 つのことを行います。TypeScript でプロジェクトを型チェックすることと、各コレクションエントリのフロントマターを、zfb.config.ts でそのコレクションに宣言された JSON Schema に対して検証することです。ビルド自体はフロントマターを検証しないため、title や date の欠けた記事はここで捕まります。CLI リファレンスを参照してください。

動作するサンプル

zfb-example-blog は、読んでそのままデプロイできるスタンドアロンのサンプルサイトです（ライブビルド）。同梱テンプレートのコピーではなく独立したリポジトリとして保守されているため、ファイル構成は zfb new がスキャフォールドするものとは異なります。手元のプロジェクトの写しではなく、作り込まれた実例として読んでください。この例の詳しい解説は Blog にあり、その他のサンプルはサンプルにまとまっています。

次に読むもの

Project structure — テンプレートが作成した各ディレクトリが実際に何をするのか。
Routing — pages/ がどのように URL になるか。動的ルートやキャッチオールルートも含みます。
Islands — 個々のコンポーネントをクライアントサイドのハイドレーションにオプトインする方法。
Build engine — Rust クレートが内部でどう組み合わさっているか。