最初のサイト

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

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

これは 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 にあり、その他のサンプルは サンプル にまとまっています。

Node-free のサイトを作る

スタンドアロン版をインストールし、zfb を PATH に追加してから実行します。

zfb new my-site --template node-free
cd my-site
zfb dev

node-free は package.json を持たず、pnpm install や npm install は不要です。zfb.config.json、Markdown / HTML / TSX のページ、明示的な Wind スタイルシートを使います。Markdown と HTML ページでページの書き方を確認できます。

開発サーバーの既定の URL は http://localhost:3000 です。ページやスタイルを編集するとライブリロードします。別のアドレスで起動する場合は zfb dev --port 4000 --host 0.0.0.0 を使います。

Node-free のビルドとプレビュー

開発サーバーを Ctrl+C で停止してから、同じプロジェクトで実行します。

zfb build
zfb preview

ビルドは既定で dist/ に静的ファイルを生成します。プレビューの既定の URL は http://localhost:4321 です。設定の outDir は両コマンドに適用され、CLI の --outdir が優先します。プレビューのポートは zfb preview --port 4000 で変更できます。build には --port はありません。

Node-free の検証

zfb check --skip-tsc

Node なしで TypeScript 以外のチェックを実行します。完全な TypeScript 型チェックには Node と tsc が必要です。Cloudflare アダプタを使うデプロイにも Node が必要です。Node が依然として必要なケースを参照してください。