zfb
GitHub repository

Type to search...

to open search from anywhere

v6.0.0

Created Nov 9, 2026Takeshi Takatsudo

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_BUNDLER and ZFB_ROLLDOWN_PROTOTYPE were removed (9dc29f37b, a709476ed). Setting either one, to any value including ZFB_BUNDLER=rolldown, now fails every zfb subcommand before it runs with the esbuild bundler backend and its <NAME> selector were removed; zfb always bundles natively. Unset <NAME>. (zfb --version and zfb --help still print.) This covers ZFB_BUNDLER=esbuild and ZFB_ROLLDOWN_PROTOTYPE=0, the 5.x ways to select esbuild. Unset both in scripts, CI and .env files. 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_BIN is 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 zfb executable 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 --version now reports embedded bundler: rolldown-24bc2d0 in place of embedded esbuild: <version>. Update any script that parses that second line. The short zfb -V output 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-prototype feature (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-islands renames EsbuildSubprocessBundler/EsbuildSubprocessConfig to IslandsBundler/IslandsBundlerConfig with no deprecated aliases. In the config, the extra_args and env_vars fields and with_extra_env are replaced by typed externals and conditions fields and a node_path field with with_node_path; mock_subprocess is renamed mock_bundle; and binary_path/with_binary_path and the binary version gate are removed. zfb-islands no longer re-exports EXPECTED_ESBUILD_VERSION or EXPECTED_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 in zfb-toolchain-pins, the zfb-binfetch crate, and zfb-test-utils' locate_esbuild (7f15321d1, 4cc495f22, 9e97065b9, 4aa48e0fc, 4080bdff7). There is no replacement: no bundling path takes a binary. ModuleWorkerBuildContext::from_esbuild_loader_args in zfb-build is renamed from_loader_args (7f15321d1).

  • Rust library API: the native bundler crate zfb-rolldown-prototype is renamed to zfb-bundler (zfb_bundler), and its enabled() selector and run_prepared(&Command) esbuild-argv adapter are removed (9dc29f37b, f8d035560, 3df6d502e). Build a typed BundleRequest and call zfb_bundler::bundle, or zfb_bundler::generate followed by Generated::publish, instead (cd5d81d20, 14d6b854f). The rolldown-prototype Cargo feature is removed from zfb, zfb-build and zfb-islands; drop it from --features.

  • Rust library API: a library that bundles a .ts config or a .ts/.tsx/.mts/.cts plugin now needs an explicit compiler worker launcher (5db182e6f, 9e97065b9, 4aa48e0fc). The library never derives one from current_exe(). Set zfb_config_loader::LoadOptions::compiler_worker, call ServerBuilder::compiler_worker(WorkerLauncher) in zfb-server, or pass the launcher to PluginHost::spawn_with_timeout or PluginHost::spawn_with_timeout_and_diagnostic_sink, whose fourth parameter is now Option<WorkerLauncher> instead of Option<EmbeddedEsbuildGetter>. The host executable must call zfb_server::run_compiler_worker_if_requested() (or zfb_compiler_worker::run_if_requested()) first in main. A .ts config without a launcher fails with an error naming the missing launcher. A zfb.config.json config 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.ts and TypeScript-family plugin entries are bundled by a supervised native compiler worker, a child process of the zfb executable, instead of an esbuild subprocess (5db182e6f, 9e97065b9, 4aa48e0fc). The config keeps its contract: Node builtins are rejected, and the zfb/config and @takazudo/zfb/config aliases resolve. Plugins keep Node 22 output, inline source maps, the require shim and external packages; aliases, tsconfig paths/baseUrl and 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 &amp;. With minifyHtml on, a rendered a &amp; b came out as a & b, which is valid HTML but fails html-validate's no-raw-characters rule (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 with ZW001. Plain .html and Markdown still report ${ as a malformed class candidate (85cb08db8, 5e6602458, 9c0f06d46, 71db2ee09, e43face31, #4647).

Revision History

Takeshi TakatsudoCreated: 2026-11-09T18:51:55+09:00Updated: 2026-11-09T18:51:55+09:00