プラグイン

zfb プラグインの作成と利用 — 4 つのライフサイクルフック、仮想モジュール、インポートエイリアス、開発専用の注入ルート。

概要

zfb プラグインは、ZfbPlugin オブジェクトをデフォルトエクスポートする ES モジュールです。zfb の build / dev ホストは各プラグインモジュールを起動時に一度ロードし、4 つのライフサイクルフックを順次ディスパッチします。

import { definePlugin } from "@takazudo/zfb/plugins";

export default definePlugin({
  name: "my-plugin",
  setup?(ctx) {},        // #255 — ホスト起動時に一度、preBuild の前
  preBuild?(ctx) {},     // バンドラ / レンダラ前のファイル生成
  postBuild?(ctx) {},    // dist/ への書き出し後の仕上げ処理
  devMiddleware?(ctx) {},// zfb dev でのリクエスト単位 HTTP ハンドラ
});

4 つのフック

• setup(ctx) — addAlias / addVirtualModule / injectRoute で仮想モジュール、インポートエイリアス、開発専用の合成ルートを登録します。ctx.command が "build" か "dev" かで分岐できます。
• preBuild(ctx) — バンドル前にファイルを生成する用途。
• postBuild(ctx) — dist/ 書き出し後の仕上げ。ctx.routes にビルドが生成した全 URL のルートマニフェストが渡されます（preBuild では undefined）。
• devMiddleware(ctx) — リクエストごとに { status, headers, body } を返す HTTP ハンドラ。injectRoute がページレンダリングパイプラインを通すのに対し、こちらは JSX を介さない素の HTTP 応答です。

設計上の制約

• addAlias のコントラクトは 完全一致のみ ですが、現状 1 系統だけ振る舞いが異なります。SSR と paths() を実行する組み込み V8 ホストは完全一致を遵守します。一方、"use client" 島をバンドルする islands esbuild 経路は esbuild CLI の --alias フラグに依拠しており、これがプレフィックス + スラッシュ一致のため @/foo を登録すると @/foo/bar も書き換えてしまいます。両系統を完全一致に揃える作業は v1 フォローアップで追跡されます。当面は実際に import する specifier のみをエイリアス登録するのが安全です。
• addVirtualModule(specifier, loader) の loader は 完全な ESM ソーステキスト を返します。loader はビルドごと（および dev ホスト起動ごと）に最初の import のタイミングで 1 回だけ 実行され、結果はキャッシュされます。
• injectRoute は dev 専用。zfb build 中に呼ぶと InjectRouteInBuildMode で失敗します。なお v1 ではレジストリへの登録・衝突検出・パターンマッチングまでが対象で、マッチした entrypoint を実際にページレンダラで評価する処理は後続イシューで対応します（マッチ自体は zfb_plugin トレースに記録されます）。
• 同じキー（エイリアスの from / 仮想モジュールの specifier / 注入ルートの pattern）を 2 つのプラグインが異なる値で登録すると衝突エラーで両方のプラグイン名を含めて中断します。
• SetupContext には addRemarkPlugin などのマークダウン拡張面は 意図的に存在しません。マークダウン関連は zfb 本体（Rust 側）に内包する方針です。

詳細は英語版を参照してください。