v6.0.0
v6.0.0
Released: 2026-11-09
Breaking Changes
zfb no longer contains, downloads or runs esbuild. Every bundling path now uses the embedded native Rolldown bundler: pages and SSR, islands, standalone client scripts and their module workers, zfb.config.ts, and TypeScript-family plugins. In 5.x, the zfb CLI and the npm-installed binary already bundled pages, islands, client scripts and their module workers with Rolldown by default, but still compiled zfb.config.ts and TypeScript plugins with esbuild. Rust hosts that embedded zfb crates without the rolldown-prototype feature, such as through zfb-server, bundled every path with esbuild. The esbuild backend and its options are gone. The v6 migration guide covers each change below.
The bundler selectors
ZFB_BUNDLERandZFB_ROLLDOWN_PROTOTYPEwere removed (9dc29f37b, a709476ed). Setting either one, to any value includingZFB_BUNDLER=rolldown, now fails everyzfbsubcommand before it runs withthe esbuild bundler backend and its <NAME> selector were removed; zfb always bundles natively. Unset <NAME>.(zfb --versionandzfb --helpstill print.) This coversZFB_BUNDLER=esbuildandZFB_ROLLDOWN_PROTOTYPE=0, the 5.x ways to select esbuild. Unset both in scripts, CI and.envfiles. If a site still needed the esbuild workaround, report the failing build as a bundler issue. Only the CLI checks these variables; the Rust crates ignore them.ZFB_ESBUILD_BINis no longer read. Before, it named the esbuild binary for a build, an installed CLI, or an embedding host. The CLI, the Rust crates and a source build now ignore it (7f15321d1, 4cc495f22, a709476ed, 9e97065b9, 4aa48e0fc). Remove it from your environment. The wrangler/workerd pins are unchanged.The
zfbexecutable and the five native carrier packages no longer embed an esbuild binary, and a source build no longer downloads, verifies or stages one (7f15321d1).zfb --versionnow reportsembedded bundler: rolldown-24bc2d0in place ofembedded esbuild: <version>. Update any script that parses that second line. The shortzfb -Voutput is unchanged.Cache and build identities move with the backend (7f15321d1, a709476ed). The module-worker cache envelope is now ABI v3 keyed on the bundler identity, and the islands build token hashes the bundler identity instead of the esbuild version. The first build after the upgrade rebuilds those entries, and pages built with 5.x carry a different island build token than pages built with 6.0.0.
Rust embedding hosts now bundle pages and SSR, islands, client scripts and module workers with Rolldown, where 5.x used esbuild unless the host enabled the
rolldown-prototypefeature (9dc29f37b, a709476ed). Rebuild the site through the host and compare the output with a 5.x build before you ship.Rust library API: arbitrary esbuild argument and environment passthrough is gone (a709476ed).
zfb-islandsrenamesEsbuildSubprocessBundler/EsbuildSubprocessConfigtoIslandsBundler/IslandsBundlerConfigwith no deprecated aliases. In the config, theextra_argsandenv_varsfields andwith_extra_envare replaced by typedexternalsandconditionsfields and anode_pathfield withwith_node_path;mock_subprocessis renamedmock_bundle; andbinary_path/with_binary_pathand the binary version gate are removed.zfb-islandsno longer re-exportsEXPECTED_ESBUILD_VERSIONorEXPECTED_ESBUILD_SHA256.Rust library API: esbuild resolver and getter items are removed:
EmbeddedEsbuildGetter,resolve_esbuild_binary_with_handle,resolve_esbuild_binary_with_env,DEFAULT_ESBUILD_SLOT,BundlerInput::esbuild_binary,render_pipeline::embedded_binary, the esbuild pin and override policy inzfb-toolchain-pins, thezfb-binfetchcrate, andzfb-test-utils'locate_esbuild(7f15321d1, 4cc495f22, 9e97065b9, 4aa48e0fc, 4080bdff7). There is no replacement: no bundling path takes a binary.ModuleWorkerBuildContext::from_esbuild_loader_argsinzfb-buildis renamedfrom_loader_args(7f15321d1).Rust library API: the native bundler crate
zfb-rolldown-prototypeis renamed tozfb-bundler(zfb_bundler), and itsenabled()selector andrun_prepared(&Command)esbuild-argv adapter are removed (9dc29f37b, f8d035560, 3df6d502e). Build a typedBundleRequestand callzfb_bundler::bundle, orzfb_bundler::generatefollowed byGenerated::publish, instead (cd5d81d20, 14d6b854f). Therolldown-prototypeCargo feature is removed fromzfb,zfb-buildandzfb-islands; drop it from--features.Rust library API: a library that bundles a
.tsconfig or a.ts/.tsx/.mts/.ctsplugin now needs an explicit compiler worker launcher (5db182e6f, 9e97065b9, 4aa48e0fc). The library never derives one fromcurrent_exe(). Setzfb_config_loader::LoadOptions::compiler_worker, callServerBuilder::compiler_worker(WorkerLauncher)inzfb-server, or pass the launcher toPluginHost::spawn_with_timeoutorPluginHost::spawn_with_timeout_and_diagnostic_sink, whose fourth parameter is nowOption<WorkerLauncher>instead ofOption<EmbeddedEsbuildGetter>. The host executable must callzfb_server::run_compiler_worker_if_requested()(orzfb_compiler_worker::run_if_requested()) first inmain. A.tsconfig without a launcher fails with an error naming the missing launcher. Azfb.config.jsonconfig and JavaScript plugins need no launcher. See Embed as library.
esbuild removal covers what zfb owns: the shipped executable, the native carriers and every bundling path. It is not a claim that every dependency graph is esbuild-free. No published zfb package depends on esbuild, but third-party development tools such as wrangler, Vitest and tsx still bring it in transitively.
Features
zfb.config.tsand TypeScript-family plugin entries are bundled by a supervised native compiler worker, a child process of thezfbexecutable, instead of an esbuild subprocess (5db182e6f, 9e97065b9, 4aa48e0fc). The config keeps its contract: Node builtins are rejected, and thezfb/configand@takazudo/aliases resolve. Plugins keep Node 22 output, inline source maps, thezfb/ config requireshim and external packages; aliases, tsconfigpaths/baseUrland package imports resolve before a package is treated as external. The worker writes only into a private directory, and zfb publishes a file only after it checks the file's identity, size and SHA-256.
Bug Fixes
HTML minification keeps
&. WithminifyHtmlon, a rendereda & bcame out asa & b, which is valid HTML but fails html-validate'sno-raw-charactersrule (69c05661f, #4650).zudo-wind: a class attribute inside a
<script>element of markup carried in a JS string (such as an inlined HTML document) reads${...}as an interpolation. Before,label-${kind}reached the compiler as one class candidate and failed the build withZW001. Plain.htmland Markdown still report${as a malformed class candidate (85cb08db8, 5e6602458, 9c0f06d46, 71db2ee09, e43face31, #4647).