Keep require() of node builtins as written on both runtime transpile paths

[robobun]

Problem

• require.resolve("fs") returns "node:fs" in a file loaded with import / import(), and "fs" in the same file loaded with require(). Node returns "fs" (and "node:fs" only for require.resolve("node:fs")).
• Same rewrite, more symptoms in files loaded with import: require("fs") ignores a require.cache["fs"] entry (node and bun's require() path honor it), a Module._resolveFilename override sees "node:fs" instead of "fs", and require("internal/cluster/round_robin_handle") (vendored node tests, --expose-internals) throws Cannot find module 'internal:cluster/RoundRobinHandle'.
• For files of 4 KiB or more the result also depends on history: both paths share the on-disk transpiler cache, so after a run that loaded such a file with import, a later run that require()s it replays the rewritten output and returns "node:fs" too (probe in the details below).
• Cause: the runtime has two copies of the import-record pre-pass that maps specifiers through the builtin alias table, and they disagree.
  • The JS-thread copy (Linker::link, src/bundler/linker.rs, skip added in module pr 2 #18266, bun 1.2.6) leaves require() / require.resolve() records of builtins as written. The runtime resolver (VirtualMachine::resolve_maybe_needs_trailing_slash, src/jsc/VirtualMachine.rs) then maps the written name to the module, returns the written name itself for require.resolve of a node builtin, and overridableRequire (src/js/builtins/CommonJS.ts) looks up require.cache under the written name.
  • The concurrent transpiler's copy (TranspilerJob::run, src/jsc/RuntimeTranspilerStore.rs) never got that skip. It prints the table's path in place of the name, which defeats all of the above, and for internal/cluster/round_robin_handle prints a path (internal:cluster/RoundRobinHandle) the resolver does not accept at all.
• The JS-thread copy has a defect of its own: since Eliminates special handling for bun:test in the transpiler #22888 (bun 1.3.1) moved the @jest/globals / vitest aliases into the same table, its skip leaves require("@jest/globals") as written too, and the runtime resolver looked the name up without the test-mode entries. Under bun test that require() fails with Cannot find module '@jest/globals' in the test file itself and in any require()d file (@jest/globals not rewritten to bun-test when using CommonJS require to import #4466 again); it only worked in files loaded with import, where the store rewrote it.

Fix

• One shared function, Alias::rewrite_import_record (src/resolve_builtins/HardcodedModule.rs), replaces both loop bodies; the linker's private adapter module over Alias::get is deleted. The rule is the linker's existing one: a require() / require.resolve() record of any Tag::Builtin entry stays as written, everything else (import, import(), and "bun" itself, which the printer inlines as globalThis.Bun) is rewritten as before.
  • Correct because the resolver accepts the names in the table and not necessarily the paths, and because node's require.resolve / require.cache / _resolveFilename behavior is defined in terms of the written name. Leaving the record alone hands the resolver exactly what it handles; this is the output every entry point and every require()d file has had since 1.2.6.
  • Both paths now print a given file identically, which the shared transpiler cache requires anyway.
• VirtualMachine::_resolve and resolve_maybe_needs_trailing_slash look the name up with the VM's rewrite_jest_for_tests (builtin_alias_cfg()), so under bun test a require() of @jest/globals / vitest resolves to bun:test on both paths, the same way import of them already did. Outside bun test the flag is false and nothing changes.
• Runtime transpiler cache version 25 -> 26, so entries the concurrent transpiler wrote with rewritten specifiers are not replayed (same reason as version 17, the previous change to this rewrite).
• Verified:
  • test/js/node/module/node-module-module.test.js, new require() of node builtins keeps the written specifier on every transpile path: one probe file loaded three ways (require(), static import, import()) reports require.resolve of fs / node:fs / sys, whether require.cache["fs"] is honored for fs and not for node:fs, and what a _resolveFilename override sees; expected values are what node prints for the same file. Run with the concurrent transpiler on and off. Fails on the released binary for the two import loads.
  • test/js/bun/resolve/require.test.ts, new require() resolves the alias on both transpile paths: internal/cluster/round_robin_handle (the entry whose path is not a resolvable name) and ffi required from a require()d and an import()ed file. Fails on the released binary for the import()ed file; also the case that rejects skipping only node builtins, which a first version of this change did and test/js/node/test/parallel/test-cluster-accept-fail.js caught in CI (that test passes again).
  • test/js/bun/test/bun_test.test.ts, new require() of @jest/globals and vitest resolves to bun:test on every transpile path: the test file, a require()d helper and an import()ed helper each require() both aliases and require.resolve one. Fails on the released binary for the first two (MODULE_NOT_FOUND); the import() case pins the behavior that already worked.
  • Still passing locally: the rest of those files, test/js/node/module/*, test/js/bun/resolve/{import-meta,import-meta-resolve,resolve,resolve-error,builtin-esm-lazy-exports}, test/js/node/missing-module.test.js, test/cli/run/{transpiler-cache,require-and-import-trailing}.test.ts, test/regression/issue/{25707,09739}.test.ts, test/js/first_party/undici/undici-primordials.test.ts, test/js/node/test_runner/node-test.test.ts, test/js/bun/test/{fake-timers,test-auto-import-jest-globals,jest-extended,expect-extend,mock/mock-module}, test/js/node/test/parallel/{test-require-node-prefix,test-stream-iter-disabled,test-cluster-accept-fail}.js, and the test/internal/source-lints dead-export / byte-search lints. The RSS leak tests in test/cli/run/require-cache.test.ts exceed their time and memory budgets on the local debug ASAN build; the files they reload in a loop contain no import records, so this pass never runs in them.
• Resolve bare undici to the installed package, keep the shim as fallback #36102 edits the two old loop bodies separately (it predates transpiler cache version 24); after a rebase its change is one condition inside rewrite_import_record.

Background

• Runtime transpile paths: the entry point, every file reached through require(), and everything when a plugin is registered are transpiled on the JS thread (transpile_source_code -> Linker::link). Files reached through import statements or import() are transpiled on a thread pool by RuntimeTranspilerStore (BUN_FEATURE_FLAG_DISABLE_ASYNC_TRANSPILER=1 turns that off, which is how the tests run a case on both paths). Each path runs its own pre-pass over the file's import records before printing.
• Import record: the parser's entry for each import, import(), require() or require.resolve() in a file; kind says which (is_common_js() is require or require.resolve) and the printer emits path.text as the specifier, so rewriting it here changes the string the runtime later receives.
• Builtin alias table (src/resolve_builtins/HardcodedModule.rs): maps names to built-in module paths, e.g. fs -> node:fs, sys -> node:util, ffi -> bun:ffi, internal/cluster/round_robin_handle -> internal:cluster/RoundRobinHandle, and, only when Cfg::rewrite_jest_for_tests is set (bun test), @jest/globals / vitest -> bun:test. Resolution (Alias::get) is keyed by name; the fetch step that serves the module is keyed by path.
• Runtime transpiler cache: on-disk cache of printed output for source files of 4 KiB or more, keyed by source hash plus parser options, written and read by both transpile paths; EXPECTED_VERSION is bumped whenever the output for unchanged input changes.
• src/runtime/jsc_hooks.rs also contains a resolve_hook with the same alias lookup; it is installed in LoaderHooks but nothing dispatches that field, so it is left alone here.

Shared-cache probe on the released binary (1.4.0)

big.cjs is module.exports = require.resolve("fs"); padded past 4 KiB; BUN_RUNTIME_TRANSPILER_CACHE_PATH points at an empty directory.

$ bun via-import.js     # await import("./big.cjs")
import(): node:fs
$ bun via-require.js    # require("./big.cjs"), cache hit
require(): node:fs

# fresh cache directory, reversed order
$ bun via-require.js
require(): fs
$ bun via-import.js
import(): fs

Superseded first version

The first commit skipped the rewrite only for entries with node_builtin set and rewrote the remaining require() records on both paths, on the theory that the resolver maps every other entry's path back to the same module. That holds for every entry except internal/cluster/round_robin_handle, whose path is not a name the resolver accepts, so it broke test-cluster-accept-fail.js on the JS-thread path. The current version keeps the linker's Tag::Builtin rule instead and fixes the jest aliases in the resolver, which is also where a require() of them has to be handled for files the store transpiles.

[robobun]

Status: reproduced on the released 1.4.0 binary and on main; fix and tests pushed (current revision: require() of every builtin stays as written on both transpile paths, jest aliases applied by the resolver under bun test); waiting on CI.

Reproduced with:

• test/js/node/module/node-module-module.test.js (require() of node builtins keeps the written specifier on every transpile path): the two import loads return node:fs / node:util, skip require.cache["fs"], and show node:os to a _resolveFilename override.
• test/js/bun/resolve/require.test.ts (require() resolves the alias on both transpile paths): the import()ed file throws Cannot find module 'internal:cluster/RoundRobinHandle'.
• test/js/bun/test/bun_test.test.ts (require() of @jest/globals and vitest resolves to bun:test on every transpile path): MODULE_NOT_FOUND in the test file and the require()d helper.

All three pass with this branch, as does test/js/node/test/parallel/test-cluster-accept-fail.js, which the first revision of this PR broke; see the PR description for the other suites run.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: c42e323d-a181-4a88-a7fe-3afe5edf1914

📥 Commits

Reviewing files that changed from the base of the PR and between 23d535a and 3cde0cd.

📒 Files selected for processing (6)

• src/bundler/linker.rs
• src/jsc/RuntimeTranspilerCache.rs
• src/jsc/RuntimeTranspilerStore.rs
• src/resolve_builtins/HardcodedModule.rs
• test/js/bun/test/bun_test.test.ts
• test/js/node/module/node-module-module.test.js

Included review availability: Your plan includes up to 5 reviews per rolling hour; 0 remain after this review.

---

Walkthrough

Changes

The PR centralizes hardcoded alias rewriting for the linker and runtime transpiler. It preserves written Node builtin specifiers, updates the transpiler cache format, and adds integration coverage for aliases and builtin resolution.

Hardcoded alias rewrite

Layer / File(s)	Summary
Centralized import-record rewriting src/resolve_builtins/HardcodedModule.rs, src/bundler/linker.rs, src/jsc/RuntimeTranspilerStore.rs	Alias::rewrite_import_record handles alias lookup, Node builtin preservation, path and tag updates, and external side-effect flags. The linker and runtime transpiler use this method.
Transpiler cache compatibility src/jsc/RuntimeTranspilerCache.rs	The cache format version increases to 26 for preserved Node builtin specifiers.
Alias and builtin integration coverage test/js/bun/test/bun_test.test.ts, test/js/node/module/node-module-module.test.js	Tests cover Jest and Vitest aliases, builtin specifiers, require.resolve, _resolveFilename, require.cache, and concurrent transpiler modes.

Possibly related PRs

• oven-sh/bun#36102: Related hardcoded alias rewriting changes preserve specifiers during deferred resolution.

Suggested reviewers: jarred-sumner, cirospaciari

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the primary change: preserving written Node builtin specifiers across both runtime transpilation paths.
Description check	✅ Passed	The description explains the problem, fix, implementation details, verification steps, and test coverage, although it uses headings different from the template.

---

_{Comment @coderabbitai help to get the list of available commands.}

[robobun]

^{Updated 12:06 AM PT - Aug 16th, 2026}

✅ @robobun, your commit cb5c6dc62bcfbf6986591741f7f2607f547f7dad passed in Build #99234! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 39316

That installs a local version of the PR into your bun-39316 executable, so you can run:

bun-39316 --bun