v6 への移行
zfb 5.x のプロジェクトや組み込みホストを、esbuild を使わないネイティブバンドラーへ移行します。
はじめる前に
zfb 6 は、zfb に組み込まれたネイティブの Rolldown バンドラーですべてをバンドルします。対象はページと SSR、islands、クライアントスクリプトとその module worker、zfb.config.ts、TypeScript 系のプラグインです。zfb 5 でも zfb CLI と npm でインストールしたバイナリは、ページ、islands、クライアントスクリプトとその module worker を既定で Rolldown でバンドルしていましたが、設定ファイル、プラグイン、ZFB_BUNDLER=esbuild のフォールバックのために esbuild のバイナリを同梱していました。rolldown-prototype フィーチャーを有効にせずに zfb のクレートを組み込んでいた Rust のホスト(zfb-server 経由など)は、すべての経路を esbuild でバンドルしていました。zfb 6 は esbuild と、それを選択・設定するすべてのオプションを削除します。互換モードはありません。
既定の設定で zfb CLI を実行しているプロジェクトの多くは、ソースを変更する必要はありません。スクリプトと CI に下記の環境変数が残っていないか確認してください。zfb の Rust クレートを組み込むホストは変更点が多くなります。Rust の組み込みホストを参照してください。
これは zfb が所有する範囲の話です。公開されている zfb のパッケージはどれも esbuild に依存していません。プロジェクトで wrangler、Vitest、tsx などのツールを使っている場合、それらが esbuild をインストールすることがありますが、こちらは影響を受けません。
環境変数
シェルのプロファイル、CI のワークフロー、.env ファイル、パッケージのスクリプトから ZFB_BUNDLER と ZFB_ROLLDOWN_PROTOTYPE を削除してください。どちらかを設定すると、rolldown を含むどの値でも、zfb のすべてのサブコマンドが実行前に失敗します(zfb --version と zfb --help は出力されます)。
ZFB_BUNDLER=esbuild: the esbuild bundler backend and its ZFB_BUNDLER selector were removed; zfb always bundles natively. Unset ZFB_BUNDLER.ZFB_ESBUILD_BIN も削除してください。zfb はもう読み取らないため、ビルド時にも実行時にも効果はありません。
Rolldown でのビルド失敗を回避するために ZFB_BUNDLER=esbuild や ZFB_ROLLDOWN_PROTOTYPE=0 を設定していたサイトでは、そのフォールバックはもう使えません。ネイティブバンドラーが拒否する入力とその対処はトラブルシューティングを参照し、それ以外のビルド失敗はバンドラーの問題として報告してください。
バージョン出力とキャッシュ
zfb --version は、5.x の embedded esbuild: <version> の代わりに embedded bundler: rolldown-24bc2d0 を出力します。この 2 行目を解析しているスクリプトは更新してください。zfb -V の出力は変わりません。
module worker のキャッシュと islands のビルドトークンは、バンドラーの識別子をキーにするようになりました。アップグレード後の最初のビルドでこれらは作り直されます。手動でキャッシュを削除する必要はありません。5.x と 6.0.0 でビルドしたページは、異なる islands のビルドトークンを持ちます。
設定ファイルとプラグイン
zfb.config.ts と .ts/.tsx/.mts/.cts のプラグインエントリは、zfb 実行ファイルの子プロセスである監視付きのコンパイラーワーカーがコンパイルします。契約は変わりません。設定ファイルは引き続き Node の組み込みモジュールを import できず、プラグインは引き続き外部パッケージを残したまま Node 22 向けの ESM にコンパイルされます。CLI がワーカーを自分で起動するので、CLI の利用者は何も変更する必要がありません。
Rust の組み込みホスト
ここに挙げる変更は、zfb の Rust クレートに依存するプログラムにだけ当てはまります。前述の ZFB_BUNDLER と ZFB_ROLLDOWN_PROTOTYPE のチェックは zfb CLI のものです。クレートはこれらの変数を無視し、ZFB_ESBUILD_BIN も無視します。
すべての経路で Rolldown。 5.x では、
rolldown-prototypeフィーチャーを有効にしていないホストはページと SSR、islands、クライアントスクリプト、module worker を esbuild でバンドルしていました。また 5.x の組み込みガイドは、.tsの設定ファイルにはZFB_ESBUILD_BINを設定するよう案内していました。6.0.0 ではすべての経路が Rolldown を使います。リリース前に、ホスト経由でサイトをビルドし直し、5.x でのビルド結果と比較してください。コンパイラーワーカーのランチャー。
.tsの設定ファイルや TypeScript 系のプラグインをバンドルするライブラリには、明示的なランチャーが必要です。ライブラリがcurrent_exe()から導出することはありません。mainの最初でzfb_server::run_compiler_worker_if_requested()を呼び、ServerBuilder::compiler_worker(WorkerLauncher::new(std::env::current_exe()?).arg(COMPILER_WORKER_ARG))を渡してください。より低レベルのホストはzfb_config_loader::LoadOptions::compiler_workerを設定するか、PluginHost::spawn_with_timeoutまたはPluginHost::spawn_with_timeout_and_diagnostic_sinkにランチャーを渡します。これらの 4 番目の引数はOption<EmbeddedEsbuildGetter>からOption<WorkerLauncher>に変わりました。ランチャーがないと、.tsの設定ファイルは不足しているランチャーを名指しするエラーで失敗します。zfb.config.jsonと JavaScript のプラグインにはランチャーは不要です。ライブラリとして組み込むを参照してください。クレート名の変更。
zfb-rolldown-prototypeはzfb-bundler(zfb_bundler)になりました。zfb、zfb-build、zfb-islandsの依存からrolldown-prototypeの Cargo フィーチャーを削除してください。esbuild の argv とセレクタの廃止。
run_prepared(&Command)とenabled()は削除されました。型付きのBundleRequestを組み立ててzfb_bundler::bundleを呼ぶか、zfb_bundler::generateのあとにGenerated::publishを呼んでください。islands のバンドラー。
EsbuildSubprocessBundlerとEsbuildSubprocessConfigはIslandsBundlerとIslandsBundlerConfigになり、非推奨の別名はありません。extra_argsとenv_varsフィールド、with_extra_envは、型付きのexternalsとconditionsフィールド、node_pathフィールド(またはwith_node_path)に置き換えてください。任意の esbuild 引数に代わるものはありません。mock_subprocessはmock_bundleに名前を変え、binary_pathとwith_binary_pathは削除してください。zfb-islandsはEXPECTED_ESBUILD_VERSIONとEXPECTED_ESBUILD_SHA256を再エクスポートしなくなりました。削除された esbuild の項目。
EmbeddedEsbuildGetter、resolve_esbuild_binary_with_handle、resolve_esbuild_binary_with_env、DEFAULT_ESBUILD_SLOT、BundlerInput::esbuild_binary、render_pipeline::embedded_binary、zfb-toolchain-pinsの esbuild ピン、zfb-binfetchクレート、zfb-test-utilsのlocate_esbuildはなくなりました。呼び出しを削除してください。バイナリを受け取るバンドル経路はもうありません。zfb-buildのModuleWorkerBuildContext::from_esbuild_loader_argsはfrom_loader_argsに名前が変わりました。ソースからのビルド。
zfbをソースからビルドしても esbuild をダウンロードしたり配置したりしなくなり、ビルド時のZFB_ESBUILD_BINによる上書きもなくなりました。
チェックリスト
6.0.0 のパッケージとバイナリを揃えてインストールし、
zfb --versionでembedded bundlerの行を確認します。zfb を実行するすべての環境から
ZFB_BUNDLER、ZFB_ROLLDOWN_PROTOTYPE、ZFB_ESBUILD_BINを削除します。zfb buildを実行し、主要なページ、islands、クライアントスクリプトをブラウザーで確認します。組み込みホストでは、コンパイラーワーカーのランチャーを追加し、
zfb-rolldown-prototypeをzfb-bundlerに置き換え、削除された esbuild の API を置き換えてから、ホストをビルドし、ホスト経由でサイトをビルドし直して 5.x でのビルド結果と比較します。