defineConfig
完全な型推論つきで zfb プロジェクトの設定を定義します。
シグネチャ
defineConfig(config: ZfbConfig): ZfbConfigdefineConfig は zfb/config からエクスポートされます。このヘルパーは identity 型で、受け取った引数をそのまま返します。唯一の役割は、エディタに ZfbConfig 形状に対する IntelliSense と型チェックを提供することです。実際のスキーマは設定ロード時に Rust の serde によって検証されるため、設定を TypeScript で書いても JSON で書いても同じルールが適用されます。
zfb/config インポートの型付け
zfb.config.ts は ベア specifier の zfb/config から defineConfig をインポートします。zfb は設定ロード時にそのインポートをランタイム専用のスタブにエイリアスし（そのため @takazudo/zfb パッケージを入れていなくても設定をパースできます）、node_modules に実体としての zfb/config モジュールは存在しません。公開されている型は スコープ付き のサブパス @takazudo/ 配下にあります。そのため素の tsc --noEmit（zfb check が実行するもの）にはベアインポートを型付けする対象がなく、Cannot find module 'zfb/config' を報告します。
両者を橋渡しするには、スコープ付きパッケージの型を 再エクスポート する 1 行の ambient 宣言を使います。プロジェクトルートに zfb-shim.d.ts を追加してください（tsconfig が拾う .d.ts ならどれでも構いません）。
// zfb-shim.d.ts — ベアの `zfb/config` specifier を型付けする。
declare module "zfb/config" {
export * from "@takazudo/zfb/config";
}必ず再エクスポートにしてください — ZfbConfig の形状をシムに手書きでコピーしては いけません。手で写したフィールドリストは静かにエンジンから遅れていきます。新しい設定フィールドが追加されるたびに手で足さない限り、zfb check が妥当なフィールドを TS2353: Object literal may only specify known properties で拒否します。export * は公開されている @takazudo/ を自動的に追従するため、シムが遅れることはありません。
設定の形状
すべてのキーは camelCase です。形状は Rust の serde デシリアライザ（crates/）によって強制されます。packages/ の TypeScript 型は、エディタの IntelliSense のためにそれを反映しています。
outDir?: string— 出力ディレクトリ。デフォルト:"dist"。publicDir?: string— 静的アセットのディレクトリ。そのままコピーされます。デフォルト:"public"。host?: string— dev / preview サーバーがバインドするホスト。port?: number— dev / preview サーバーのポート。allowedHosts?: string[]— 非 localhost インターフェースにバインドしたときに dev / preview サーバーが受け付ける Host ヘッダー値（Vite のserver.allowedHostsに相当）。非ループバックバインドのときだけ参照されます。localhost・明示的にバインドしたホスト・IP リテラルの Host（127.0.0.1・[::1]・起動バナーが表示する LAN URL など）は常に許可されます（DNS リバインディングには DNS 名が必要なため、生の IP は安全です）。エントリは完全一致（大文字小文字を区別せず、リクエスト側のポートは除去して比較）。".example.com"のような先頭ドット付きエントリはサブドメインにもマッチします。framework?: "preact" | "react"— JSX フレームワークのランタイム。デフォルト:"preact"。collections?: CollectionDef[]— コンテンツコレクション。各エントリは以下を持ちます。name: string—getCollection呼び出しで使う識別子。path: string— プロジェクトルートからの相対ディレクトリ。schema?: Record<string, unknown>— フロントマター検証用の任意の JSON Schema（zfb checkで強制されます。ビルドではフロントマターの検証は行われません）。include?: string[]— glob パターン（globset 方言、pathからの相対）。設定すると、マッチするエントリのみが保持されます。exclude?: string[]— glob パターン。マッチするエントリは除外されます（includeの後に評価されます）。idStripSuffix?: string— 各エントリの slug とモジュール specifier から取り除かれるサフィックス（例: 多言語レイアウトでの".en"）。
tailwind?: { enabled?: boolean }— Tailwind オプション。prefetch?: { disabled?: boolean }— プリフェッチオプション。disabled: trueのとき、ランタイムのプリフェッチ配線はビルド時の meta タグを通じて完全にスキップされます。bundle?: { exclude?: string[]; mainFields?: string[]; external?: string[] }—--platform=neutralのページ / SSR パスに対する esbuild のエスケープハッチ。excludeは esbuild のグラフから除外するソースファイルのプロジェクト相対 glob を列挙します。mainFieldsはexportsマップを持たない依存に対する main-fields リストを上書きします。externalはベア specifier を external としてマークし、esbuild がそれをバンドルせずに残すようにします。neutral プラットフォームで失敗する CJS 専用の依存に便利です（issue #680 / #676 を参照）。plugins?: PluginConfig[]— ユーザー提供のプラグイン。各エントリはname（npm の specifier または.相対パス）と任意の/ options（プラグインのフックに渡される任意の JSON オブジェクト）を持ちます。フックのコントラクト（setup、preBuild、postBuild、devMiddleware）の全体、および仮想モジュール・インポートエイリアス・開発専用の注入ルートについては Plugins を参照してください。presets?: Partial<ZfbConfig>[]— バリデーション前にマージされる設定プリセット。各プリセットは部分的なZfbConfig形状のオブジェクトで、通常はプリセットパッケージのファクトリ関数の戻り値です。配列フィールド（plugins、collections、extraWatchPaths、allowedHosts）はプリセットから先頭に付与され、メイン設定のエントリは相対的な順序を維持します。スカラーフィールドはメイン設定がデフォルトのままのときのみプリセットの値が使われます。メイン設定は常に権威を持ちます。プリセット内のネストしたpresetsは再帰的に展開されません。プリセット作者は相対パスプラグインが正しく解決されるようdefinePresetを使ってください。adapter?: string— デプロイ先アダプタのパッケージ名。純粋な静的ビルドの場合は省略します。"@takazudo/zfb-adapter-cloudflare"のようなパッケージは SSR バンドルをデプロイ可能なエントリ（例: Cloudflare Pages 向けのdist/）にラップします。_ worker. js output?: "static" | "hybrid" | "auto"— プロジェクトの出力モード。"static"は、いずれかのルートがprerender = falseをエクスポートしているとビルド開始時にエラーになります。"hybrid"は、現在 SSR ルートが存在しなくても常に V8 / SSR を有効にします。"auto"（デフォルト）はルートセットから検出します。site?: string— 正規のオリジン URL（例:"https:）。設定すると/ / example. com" globalThis.__zfb.siteが公開され、レイアウトで正規の<link>タグ、OpenGraph メタ、サイトマップの絶対 href、hreflang の代替言語指定を構築できます。絶対 HTTP/HTTPS URL である必要があります。サーバーサイドでの正規 URL 構築が不要なビルドでは省略してください。baseとは別物です（後述）。base?: string— アセット URL 向けの公開 URL プレフィックス。サイトがサブパス配下にデプロイされる場合（例:"/pj/my-site/"）に使います。siteとは別物です。baseはアセット URL の前に付与され、siteはメタデータで使う完全な正規オリジンです。stripMdExt?: boolean— MDX コンパイル時に内部リンクの href から.md/.mdx拡張子を取り除き、末尾に/を付与します。デフォルト:false。trailingSlash?: boolean— base パスの書き換え時に、拡張子なしの絶対 href に末尾の/を付与します。デフォルト:false。markdown?: MarkdownConfig— Markdown / MDX のパースオプション（例: GFM の切り替え）。Markdown Features のセクションを参照してください。resolveMarkdownLinks?: ResolveMarkdownLinksConfig— マークダウンリンクリゾルバの設定。[label](.のリンクをレンダリング後のルート URL に書き換えるには有効にします。拡張子なし（/ other. mdx) .）およびディレクトリ形式（/ other other/）のターゲットも解決され、{name}.mdx→{name}.md→{name}/→index. mdx {name}/の順に探索されます。相対ターゲットはソースファイルのディレクトリから解決されます。非 index ページからレンダリング後の URL（ソースファイルより 1 階層深い位置 — 例:index. md section/からのarticle. mdx .）を基準に書かれたディレクトリ形式リンクは、ファイル空間の候補がすべて外れた場合に URL 空間フォールバックで解決されます。. / sibling/ emitRoutesManifest?: boolean—zfb buildがビルド後のルートマニフェストを<outDir>/に書き出すかどうか。デフォルト:_ _ zfb/ routes. json true（書き出す）。falseを設定すると抑制します。extraWatchPaths?: string[]— プロジェクト内のソースルートに加えて、dev ウォッチャーが追跡する追加の絶対ファイルシステムパス。プロジェクトルート外のパスを監視する を参照してください。
以下のキーも同じ ZfbConfig 型の一部で、defineConfig や zfb check は他のフィールドと同様に型チェックします。これらは Rust エンジンのコードレンダリングとプラグインの挙動を設定します。
codeHighlight— syntect の構文ハイライトテーマオプション。構文ハイライトのガイドを参照してください。フィールド:theme?: string— シングルテーマモード。syntect の組み込み、またはユーザーが読み込んだテーマ名（例:"InspiredGitHub"、"Solarized (dark)"）。デフォルトは"base16-ocean.dark"。トークンはインラインのcolor:で着色されます。themeLight/themeDarkとは排他です。これらは Shiki（"dracula"など）ではなく syntect のテーマ名です。themesDir?: string—.tmThemeファイルのディレクトリ。プロジェクトルートからの相対です。各ファイルは宣言されたnameによってtheme・themeLight・themeDarkから利用できます。シングル / デュアル両方のモードに適用されます。相対パスである必要があり、..でルートから抜け出すことはできません。ディレクトリが存在しない場合はビルド開始時にエラーになります。themeLight?: string— デュアルテーマハイライト用のライトモード syntect テーマ名。themeDarkと必ずセットで指定する必要があり、片方だけの指定はビルドエラーになります。themeとは排他です。ペアを設定すると、各ブロックが 2 回ハイライトされ、トークンはインラインのcolor:の代わりに--shiki-light/--shiki-darkカスタムプロパティを持ち、<pre>にはclass="syntect-dual"と--shiki-light-bg/--shiki-dark-bgが付与され、利用側はlight-dark()CSS ルールでアクティブな色を解決します。themeDark?: string— デュアルテーマハイライト用のダークモード syntect テーマ名。themeLightと必ずセットで指定し、themeとは排他です。デュアルモードの完全な仕様はthemeLightを参照してください。
pluginHookTimeoutSecs— プラグインフック呼び出しのタイムアウト（秒）。
プロジェクトルート外のパスを監視する
extraWatchPaths を使うと、プロジェクトツリー外のファイルが変更されたときに zfb dev がライブリロードできます。プロジェクトが兄弟リポジトリからコンテンツを読み込む場合、コードとともにコンテンツを同梱する file: 依存、共有ファイルシステムのディレクトリなどで便利です。
import { defineConfig } from "zfb/config";
export default defineConfig({
extraWatchPaths: [
"/home/me/knowledge-base",
"/srv/shared-content",
],
});セマンティクス:
絶対パスのみ。 各エントリは絶対パスである必要があります。相対パスは設定ロード時に
extraWatchPaths[N]: ... must be an absolute pathエラーで拒否されます。dev ウォッチャーは各エントリをプロジェクトルートの外でそのまま登録するため、相対パスを解決するためのアンカーを持ちません。正規化。 各エントリは
zfb dev起動時に一度だけ正規化されます（Path::canonicalize）。シンボリックリンクは解決され、以降のイベントは正規形でリビルドロジックに到達します。そのため、ウォッチャーが発するパスは、設定した値に対してrealpathを実行したときに得られる形と一致します。起動時に存在しない場合。 設定されたパスが
zfb dev起動時点で存在しない場合は、警告とともにスキップされます。ウォッチャーはそのパスが後から出現するかをポーリングしません。dev サーバーがすでに動いている状態でディレクトリを作成した場合は、それを認識させるためにzfb devを再起動してください。再帰的。 各エントリは再帰的に監視されます。起動後に作成されたサブディレクトリも、OS レベルの再帰監視によって自動的に拾われます。
リビルドの範囲。 これらのパスからのイベントは依存グラフのカバー範囲外にあります（グラフはツリー内のエッジのみを追跡します）。そのため、ツリー内の同等の編集よりも保守的に広範なリビルドをトリガーします。これは意図的なトレードオフで、ルート外のソースについては精度よりも正しさを優先しています。
セキュリティ上の注意。 オプトイン専用です。$HOME や / のような無制限のディレクトリを指定しないでください。Linux では再帰ウォッチャーがすべてのサブディレクトリを登録するため、大きなツリーでは inotify の max_user_watches 上限（多くのディストリビューションでデフォルト約 8192）にすぐ到達する可能性があります。広大なソースを監視する必要がある場合は、実際に編集するファイルを含む最も狭いサブツリーを監視してください。
これは dev モードの機能です。プロダクションビルド（zfb build）はファイルシステムを一度スナップショットし、ウォッチャーのイベントに依存しないため、extraWatchPaths は出力される成果物に影響しません。
例
// zfb.config.ts — 推奨される形式
import { defineConfig } from "zfb/config";
export default defineConfig({
outDir: "dist",
framework: "preact",
collections: [
{
name: "blog",
path: "content/blog",
},
],
tailwind: { enabled: true },
});ローダーは zfb.config.ts（推奨）と zfb.config.json（レガシーのフォールバック）を受け付けます。zfb.config.json のみが存在する場合は serde_json 経由で読み込まれます。.、.、または絶対パスとして宣言されたプラグインパスは設定ファイルからの相対で解決されます（"@takazudo/some-plugin" のような npm specifier はどちらの形式でも動作します）。
// zfb.config.json — レガシー形式。現在もサポート
{
"outDir": "dist",
"framework": "preact",
"collections": [
{
"name": "blog",
"path": "content/blog"
}
],
"tailwind": { "enabled": true }
}バリデーション
ローダーは以下のルールを強制し、JSON のパース失敗についてはファイルパスと line:column を添えてエラーを報告します。
コレクション名は一意である必要があります。
pathは絶対パスにできません。pathはプロジェクトルートから抜け出す..セグメントを含めることができません。