Repository navigation
Conversation
A classic script declares its top-level `var`, `function` and `class`
names on the global object before it runs. `bun build --target=browser`
keeps each top-level binding of an ES module polyfill as such a
declaration. So a binding with the name of a global does one of these:
- It hides a global that the host inherits. `var { URL, URLSearchParams }
= globalThis` leaves both `undefined` in a content script of Firefox
and in a service-worker script of workerd, where `url.parse()` then
throws `TypeError: URL is not a constructor`.
- It replaces the global. `export const browser = true` replaces the
extension API of a content script.
- It declares a global on a host that has none.
Seven such bindings were left: `File`, `Blob`, `TextEncoder`,
`TextDecoder`, `URL`, `URLSearchParams` and `browser`. Each has another
local name now and is exported with `export { local as name }`.
The default export that build-fallbacks.ts adds reads `local` for such
an export. The build fails for an export that is not a binding of the
file.
The test browser/NodePolyfillsDeclareNoPageGlobal lists the names that
the bundle of each polyfill declares, and `bun lint` says which of them
are globals of a page, a worker or an extension.
|
Updated 1:20 AM PT - Nov 12th, 2026
❌ @robobun, your commit b480e09 has 1 failures in 🧪 To try this PR locally: bunx bun-pr 48663That installs a local version of the PR into your bun-48663 --bun |
|
Status: ready for review. One CI test is red: a file-size check that the base of this stack still has. PR: #48663 (base: the branch of #41533). CI. How I reproduced the bug, with the default output of
The first two also fail with bun 1.4.3-canary.1. |
There was a problem hiding this comment.
Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.
Beyond the inline findings, I also checked whether the new throw in build-fallbacks.ts for exports without a local binding (destructured export const {...}, export ... from) can fire on the current tree: every polyfill that uses those forms (console, domain, http, https, punycode, querystring, string_decoder, sys, zlib) already has an explicit default export, so needsDefault is false for them and the synthesized default is only generated for files whose exports the regex covers. I did not run the polyfill build or the bundler test suite; the "0 names after" claim rests on the PR's own runs.
Extended reasoning...
The change renames six global-shadowing bindings in four browser polyfills (buffer, process, url, util) to local names re-exported under the original name, extends the codegen in build-fallbacks.ts with a regex scan so the synthesized default export reads the local binding, and adds three bundler tests plus a README section. It touches no security-sensitive surface. Four findings were posted inline (a classic-script behavior change for pages that replace globals after load, a lint spawn that ignores exit code and stderr, a regex that misses destructured exports, and duplicated rationale comments), so a human should weigh the behavior change; the ruled-out note records that the codegen throw is unreachable for the polyfills currently in the tree.
…added default export
The default export that build-fallbacks.ts adds reads an export as a
binding of the same name, unless `export { local as name }` gives
another one. So `export const { a, b } = x` builds again. The build
fails only for names that another module exports.
The by-name test checks the exit code of the linter and shows what the
linter printed. The comments at the renamed bindings point at the
README, which also says that such an export has the value of load time.
|
Thanks for the review. b480e09 takes three of the four suggestions:
I kept the read at load for the six exports. A module script always had it, and on the base a classic script followed a later global only through a named or a namespace import, not through the default import. The README now states the value of such an export, and the run The 23 built polyfills are byte-identical to the ones of the first commit. |
Merge into the branch of #41533.
Problem
var URL = globalThis.URL). A classic script declaresURLfirst, so a host that inheritsURLreadsundefined:url.parse()throwsTypeError: URL is not a constructorin a Firefox 160 content script and in workerd. Regression of v1.2.14 (Fix Node browser fallbacks to have util.inherit and other size improvements #19783).export const browser = true(src/node-fallbacks/process.js:52) replaces the extension API: in a Chrome 153 content script,browser.runtime.getURLthrowsTypeError: Cannot read properties of undefined (reading 'getURL').Fix
export { local as name }.build-fallbacks.tsreadslocalfor the default export that it adds.browser/NodePolyfillsDeclareNoPageGlobal: 7 such names in 13 of 23 bundles before, 0 after.test/bundler/bundler_browser.test.ts(4 cases fail on node-fallbacks: bind free process and Buffer in the browser polyfills, fix util, process and timers, make require() of assert and events callable #41533), Firefox 160, Chrome 153, workerd. Self-reviewed: 34 concerns raised, 26 addressed (Notes).Background
bun build --target=browserinlinessrc/node-fallbacks/fornode:ximports. A polyfill's top-level binding stays a top-levelvar.<script src>, extension content script) declares its top-level names on the global object.--format=iifeis experimental.Downsides
Buffer,env) and user names (Function conflict usingbun buildtogether with Chart.JS #14110) are still shared.Notes
Why a PR into the branch of #41533. #41533 owns the rule "no binding with the name of a global". It also makes
browserworse: its build bindsprocessfor the npm packages with an import of the process polyfill, so thebrowserbinding is in the bundle of 7 of 23 polyfills (assert, crypto, http, https, process, stream, zlib). On main it is in 1 (process). I cannot push to #41533, so this PR has its branch as the base. Merging it adds the commit to that branch. No user reported any of the seven names. The six alias names also break on main today, so a cut against main is possible if that is preferred.The three ways such a binding breaks a classic script. The script declares its top-level
var,functionandclassnames on the global object before it runs.File,Blob(buffer.js),TextEncoder,TextDecoder(util.js),URL,URLSearchParams(url.js).browser(process.js).TextEncoder. On such a host the bundle declared one.What I ran. Bundles are the default output of
bun build --target=browser, built with the debug build of this branch. "Before" is the #41533 head61411816a4e.["bundle.js", "after.js"]. The entry imports a CommonJS dependency that requiresutilandurl, andURLfromnode:url,Blobfromnode:buffer. Before, and with bun 1.4.3-canary.1:TextEncoder is not a constructor,URL is not a constructor,Blob is not a constructorin the bundle, and the six are own properties with the valueundefinedinafter.js. After: all work, no own property.serviceWorkerScript, entryimport { parse } from "node:url". Before, and with bun 1.4.3-canary.1:TypeError: URL is not a constructor,globalThis.URLisundefined (own). After:example.com,URLis inherited. A bundle built with bun 1.2.13 works (var { URL: J, URLSearchParams: X } = globalThis), one built with 1.2.14 throws. Fix Node browser fallbacks to have util.inherit and other size improvements #19783 (8aae5342704) replacedesbuild --minifywithbun build --minify-syntaxfor the polyfills, so their names are no longer mangled.["pre.js", "bundle.js", "post.js"], entryimport { Readable } from "node:stream"; const api = globalThis.browser ?? globalThis.chrome;. Before:typeof apiisbooleanin the bundle, andbrowser.runtime.getURLthrows inpost.js. After:browseris the extension API in both.The default export.
build-fallbacks.tsgives an ES module without a default export one that has every named export. It wrote{ TextEncoder, ... }, which reads a binding calledTextEncoder. With the export renamed, that is the global:ReferenceErroron a host without it. The build now readslocalforexport { local as name }, and the name of the export for any other one. It fails for names that another module exports (export ... from). The 23 built polyfills are byte-identical to a build with hand-written defaults inutil.jsandprocess.js.The by-name test. It builds each polyfill alone, because the bundler numbers a binding when another module of the bundle reads a global of that name (one bundle of all polyfills hides
escape).node:vmcontext whose global object it emptied, with a first statement that throws. The engine declares thevarandfunctionnames and runs nothing. Classes come from the text.bun lintwithno-undefand the environments browser, worker, serviceworker, webextensions. A name that it does not report is a global. With the names ofObject.prototype, that table knows 1,219 of the 1,243 names ofwindowin Chrome 153.no-redeclarewithbuiltinGlobalsis the direct rule, but with an ESLint 8 config its table knows 806 (noURLPattern), and with an oxlint config it knows ECMAScript names only and reports every scope.browser,escape, a classFileand a numberedqueueMicrotask. The test expects exactly those four, so a run that sees nothing fails.escapeback inquerystring.js,var console = globalThis.consoleinconsole.js(the first line ofconsole.jsin bundler: return themodule.exportsexport from require() of an ES module #42092),const Symbol = globalThis.Symbolintimers.js(printed asSymbol2).Behaviour change in a classic script. Before, a binding such as
var TextEncoderwas the property of the global object. A page that defined or replaced the global after the bundle also changed the export. Now each of the six is read once, when the bundle loads, as in a module script.browser/NodePolyfillExportsOfGlobalshas a run for it, and the README ofsrc/node-fallbacksstates it.Numbers (#41533 head against this PR).
buffer.js,process.js,url.jsandutil.jschange.constants.jsandos.jsare byte-identical.import constants from "node:constants": +0 B. Minified one-polyfill bundles that change in size: 0 of 23. Plain ones: 13 of 23 grow by 30 to 224 B..namevalues changed: 0.Not fixed here. These still share a name with the page in a classic script.
Buffer, and the bindings ofprocess.js(env,title,version,on,emit).import * as data from "./data.json"prints the keys as top-levelvars (var name).import { setTimeout } from "node:timers/promises"(a builtin without a polyfill) printsvar {setTimeout} = (() => ({}));.bun buildtogether with Chart.JS #14110).webkitnames.--format=iifeshares no name. It is marked experimental indocs/bundler/index.mdx, and a bundle with a CommonJS entry never runs that entry.Other open PRs in these files. #42092 has
var console = globalThis.console;inconsole.js: the new test reports it. #48629 adds a secondexport { local as name }line toutil.js: the default export reads it.Self-review. 34 concerns, 26 addressed: the default export is read from the source, the by-name test sees the names that a context owns and the numbered ones and has a script that must be reported, the tests have a host that inherits its globals and one that changes them later. Not done: 5 ask for these commits in #41533 itself (this PR has its branch as the base), 1 asks for a cut against main with all 16 names of main (that overlaps #41533), 2 ask for reserved names in the renamer (a question for #14110).