Skip to content

build: bundle the node fallbacks with esbuild - #41315

Open
robobun wants to merge 5 commits into
robobun/c7912907/codegen-bindgenfrom
robobun/c7912907/codegen-fallbacks
Open

robobun wants to merge 5 commits into
robobun/c7912907/codegen-bindgenfrom
robobun/c7912907/codegen-fallbacks

Conversation

@robobun

@robobun robobun commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator

Stacked on #41314. The diff is against that branch.

Problem

  • build-fallbacks.ts runs bun build through Bun.$ for each file in src/node-fallbacks. The react-refresh.js edge runs bun build too. So both need bun.

Fix

  • build-fallbacks.ts calls esbuild.build() with the same options, and runs with cfg.jsRuntime. The text fix-ups after the build do not change.
  • Only the sibling fallback files go in external. platform: "node" keeps the builtin modules external by exact name. An external entry also matches subpaths, so "util" would leave the require("util/") of the npm polyfill unbundled.
  • react-refresh.js moves to the existing esbuild rule.
  • Verified: each output file keeps the same require and import specifiers as the bun output. Node and bun write the same files, on Linux and on Windows.

Background

  • These files are the polyfills that bun build --target=browser puts in place of node builtins. Release builds embed them, zstd-compressed.
  • A debug build reads them from the codegen directory at run time. So the new files can be tested with a debug binary that was built before this change.
Notes
  • With the new files in a debug build: bundler_browser.test.ts (23 pass), bundler_regressions.test.ts (9 pass), and bundler_loader.test.ts (59 pass). These are the same results as with the old files.
  • A browser bundle that imports all 23 polyfills exports the same names with the old and the new files. One difference: the name, length, and prototype keys of the assert default export are not enumerable now. That matches the npm package.
  • esbuild keeps license comments at the end of a file. Bun dropped most of them.
  • Size: net.js is smaller (bun folded the regex template strings). timers.js and string_decoder.js are larger (esbuild's CommonJS helpers).

build-fallbacks.ts calls esbuild.build() with the options it gave to
bun build, and runs with cfg.jsRuntime. react-refresh.js moves to the
esbuild rule.

Only the sibling fallback files go in external. platform "node" keeps
the builtin modules external by exact name. An external entry also
matches subpaths, so "util" would leave require("util/") unbundled.
Each output file keeps the same require and import specifiers as
before.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — a clean step on the documented codegen_bun → codegen migration.

What was reviewed:

  • esbuild.build() options map 1:1 to the removed bun build flags; platform: "node" externalizing builtins by exact name (vs. external's subpath match) is the right call for the require("util/") case.
  • The new codegen/esbuild edges match the existing pattern in emitRuntimeJs/emitBunError exactly, including o.rootInstall for the root-node_modules esbuild package.
  • Checked that cfg.jsRuntime under Node handles the script's top-level await and import from src/node-fallbacks/ (its package.json has no "type") — Node's module-syntax detection covers it, and the MODULE_TYPELESS_PACKAGE_JSON warning is already suppressed in resolveToolchain.
Extended reasoning...

Overview

This PR migrates two emitNodeFallbacks build edges off bun-only tooling: build-fallbacks.ts moves from Bun.$-spawned bun build invocations to programmatic esbuild.build() calls and switches from the codegen_bun rule to codegen (so it runs under cfg.jsRuntime, i.e. node or bun); the react-refresh.js bundle moves from bun build to the existing esbuild rule. Both edges gain o.rootInstall as an implicit input since the esbuild package now resolves from the repo-root node_modules. The externals list in build-fallbacks.ts is trimmed to sibling fallback files only, relying on platform: "node" to externalize node builtins by exact name — avoiding esbuild's documented behavior where an external entry like "util" also matches the "util/" subpath (the npm polyfill).

Security risks

None. This is build-graph plumbing that only affects how the browser polyfill bundles are produced during Bun's own build. There is no auth, crypto, untrusted-input parsing, or network handling in the changed code. The define values, entry points, and output paths are all repo-controlled constants.

Level of scrutiny

Low-to-moderate. The change is small and mechanical, and it directly executes on a goal spelled out in scripts/build/CLAUDE.md ("Move a script to the codegen rule once it runs under node, and check that both runtimes write the same output"). The new edges copy the exact shape of neighboring esbuild-rule edges (emitRuntimeJs, emitBunError), including the o.rootInstall implicit input with the same rationale comment already present at line 426. The one thing worth verifying — that the outputs are functionally equivalent — the author addressed head-on: same import/require specifiers, same bundler test results across bundler_browser/bundler_regressions/bundler_loader, same export names from a bundle pulling in all 23 polyfills, with the residual differences (license-comment retention, minor size deltas, assert property enumerability now matching the upstream npm package) called out explicitly. Any regression here would surface as a hard build failure or a bundler-test failure, not silent corruption.

Other factors

No CODEOWNERS entry covers scripts/build/ or src/node-fallbacks/. The bug hunt ran to completion (dry_streak) with no findings and no ruled-out candidates. There are no prior reviews or unresolved threads on the PR. I confirmed the codegen rule's ${cfg.jsRuntime} $args shape accepts [script, outDir, ...] as passed, and that Node's --experimental-strip-types path (with --disable-warning=MODULE_TYPELESS_PACKAGE_JSON already baked into jsRuntime) will treat the script as ESM via syntax detection despite src/node-fallbacks/package.json lacking "type": "module", so the top-level await and import * as esbuild both work. The esbuild package is not in src/node-fallbacks/package.json, so resolution walks up to the root install — which is exactly what the new o.rootInstall implicit dep gates on.

@robobun

robobun commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator Author
Updated 9:08 PM PT - Sep 3rd, 2026

@robobun, your commit 55c44ef is building: #109987

Comment thread src/node-fallbacks/build-fallbacks.ts Resolved
@robobun

robobun commented Sep 4, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 10:54 PM PT - Sep 3rd, 2026

@robobun, your commit 121baba is building: #110049

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review found no issues

No high-confidence issues detected in this change.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review found no issues

No high-confidence issues detected in this change.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants