Migrating to v6
Move a zfb 5.x project or embedding host to the esbuild-free native bundler.
Before you start
zfb 6 bundles everything with the native Rolldown bundler compiled into zfb: pages and SSR, islands, client scripts and their module workers, zfb.config.ts, and TypeScript-family plugins. In zfb 5, the zfb CLI and the npm-installed binary already used Rolldown by default for pages, islands, client scripts and their module workers, but still shipped an esbuild binary for configs, plugins and the ZFB_BUNDLER=esbuild fallback. Rust hosts that embedded zfb crates without the rolldown-prototype feature, such as through zfb-server, bundled every path with esbuild. zfb 6 removes esbuild and every option that selected or configured it. There is no compatibility mode.
Most projects that run the zfb CLI with default settings need no source change. Check your scripts and CI for the environment variables below. Hosts that embed zfb's Rust crates have more to change; see Rust embedding hosts.
This covers what zfb owns. No published zfb package depends on esbuild. If your project uses tools such as wrangler, Vitest or tsx, they may still install esbuild, and that is unaffected.
Environment variables
Unset ZFB_BUNDLER and ZFB_ROLLDOWN_PROTOTYPE in shell profiles, CI workflows, .env files and package scripts. Setting either one, to any value including rolldown, now fails every zfb subcommand before it runs (zfb --version and zfb --help still print):
ZFB_BUNDLER=esbuild: the esbuild bundler backend and its ZFB_BUNDLER selector were removed; zfb always bundles natively. Unset ZFB_BUNDLER.Remove ZFB_ESBUILD_BIN too. zfb no longer reads it, so it has no effect at build time or run time.
If a site set ZFB_BUNDLER=esbuild or ZFB_ROLLDOWN_PROTOTYPE=0 to work around a Rolldown build failure, that fallback is gone. See Troubleshooting for the inputs the native bundler refuses and their fixes, and report any other failing build as a bundler issue.
Version output and caches
zfb --version prints embedded bundler: rolldown-24bc2d0 where 5.x printed embedded esbuild: <version>. Update scripts that parse that second line. zfb -V is unchanged.
The module-worker cache and the islands build token are now keyed on the bundler identity. The first build after the upgrade rebuilds those entries; no manual cache deletion is needed. Pages built by 5.x and 6.0.0 carry different island build tokens.
Configs and plugins
zfb.config.ts and .ts/.tsx/.mts/.cts plugin entries are compiled by a supervised compiler worker, a child process of the zfb executable. The contract is unchanged: a config still cannot import Node builtins, and plugins still compile to Node 22 ESM with external packages. The CLI starts the worker itself, so CLI users change nothing.
Rust embedding hosts
These changes apply only to programs that depend on zfb's Rust crates. The ZFB_BUNDLER and ZFB_ROLLDOWN_PROTOTYPE check above belongs to the zfb CLI; the crates ignore those variables, and ZFB_ESBUILD_BIN too.
Rolldown on every path. In 5.x a host that did not enable the
rolldown-prototypefeature bundled pages and SSR, islands, client scripts and module workers with esbuild, and the 5.x embedding guide said to setZFB_ESBUILD_BINfor a.tsconfig. In 6.0.0 every path uses Rolldown. Rebuild the site through the host and compare the output with a 5.x build before you ship.Compiler worker launcher. A library that bundles a
.tsconfig or a TypeScript-family plugin needs an explicit launcher; it never derives one fromcurrent_exe(). Callzfb_server::run_compiler_worker_if_requested()first inmain, then passServerBuilder::compiler_worker(WorkerLauncher::new(std::env::current_exe()?).arg(COMPILER_WORKER_ARG)). Lower-level hosts setzfb_config_loader::LoadOptions::compiler_worker, or pass the launcher toPluginHost::spawn_with_timeoutorPluginHost::spawn_with_timeout_and_diagnostic_sink, whose fourth parameter is nowOption<WorkerLauncher>instead ofOption<EmbeddedEsbuildGetter>. Without one, a.tsconfig fails with an error naming the missing launcher. Azfb.config.jsonconfig and JavaScript plugins need no launcher. See Embed as library.Crate rename.
zfb-rolldown-prototypeis nowzfb-bundler(zfb_bundler). Remove therolldown-prototypeCargo feature fromzfb,zfb-buildandzfb-islandsdependencies.No esbuild argv or selector.
run_prepared(&Command)andenabled()are removed. Build a typedBundleRequestand callzfb_bundler::bundle, orzfb_bundler::generatefollowed byGenerated::publish.Islands bundler.
EsbuildSubprocessBundlerandEsbuildSubprocessConfigareIslandsBundlerandIslandsBundlerConfig, with no deprecated aliases. Replace theextra_argsandenv_varsfields andwith_extra_envwith the typedexternalsandconditionsfields and thenode_pathfield (orwith_node_path). Arbitrary esbuild arguments have no replacement. Renamemock_subprocesstomock_bundle, and dropbinary_pathandwith_binary_path.zfb-islandsno longer re-exportsEXPECTED_ESBUILD_VERSIONorEXPECTED_ESBUILD_SHA256.Removed esbuild items.
EmbeddedEsbuildGetter,resolve_esbuild_binary_with_handle,resolve_esbuild_binary_with_env,DEFAULT_ESBUILD_SLOT,BundlerInput::esbuild_binary,render_pipeline::embedded_binary, the esbuild pin inzfb-toolchain-pins, thezfb-binfetchcrate andzfb-test-utils'locate_esbuildare gone. Delete the calls; no bundling path takes a binary.ModuleWorkerBuildContext::from_esbuild_loader_argsinzfb-buildis renamedfrom_loader_args.Source builds. Building
zfbfrom source no longer downloads or stages esbuild, and the build-timeZFB_ESBUILD_BINoverride is gone.
Checklist
Install matching 6.0.0 packages and binary; run
zfb --versionand confirm theembedded bundlerline.Remove
ZFB_BUNDLER,ZFB_ROLLDOWN_PROTOTYPEandZFB_ESBUILD_BINfrom every environment that runs zfb.Run
zfb buildand compare key pages, islands and client scripts in a browser.Embedding hosts: add the compiler worker launcher, rename
zfb-rolldown-prototypetozfb-bundler, and replace removed esbuild APIs; then build the host, rebuild the site through it and compare the output with a 5.x build.