lib: load fewer builtins when bootstrapping without a snapshot

[codebytere]

Worker startup gets ~6 % faster and a snapshot-less main-thread bootstrap (embedders that create their own isolate, --no-node-snapshot) ~10 % faster, by not eagerly loading builtins those paths never use. Startup with the snapshot is unchanged.

new Worker() → 'online' → terminate                       21.3 → 20.1 ms   ***   +5.9 %  ±1.4%
misc/startup-core.js mode='worker' script='semicolon.js'                   ***   +5.4 %  ±0.4%
misc/startup-core.js mode='worker' script='empty.mjs'                      ***   +3.1 %  ±0.3%
node --no-node-snapshot semicolon.js (start→exit)         58.9 → 53.4 ms   ***  +10.3 %  ±1.1%
node --no-node-snapshot empty.mjs                                          ***   +2.5 %  ±1.1%
misc/startup-core.js mode='process' (snapshot), all scripts                       ±0.5 %  n.s.

Builtins compiled: bare worker 95 → 83; --no-node-snapshot empty CJS entry 76 → 59, empty ESM entry 76 → 69.

Contexts that aren't deserialized from the snapshot compile every builtin the bootstrap touches, so each eager require there is startup time (~0.15–0.4 ms apiece). Several are eager only so that they land in the snapshot, or for features the bootstrap doesn't use. This makes them lazy without changing the snapshot's contents:

• is_main_thread.js: util, url, the ESM loader chain, internal/blob and internal/dns/utils are preloaded only if (isBuildingSnapshot()); otherwise they load on first use.
• fs → internal/blob: only for fs.openAsBlob(). internal/url → internal/data_url: only for the Buffer-returning file-URL helpers. execution, cjs loader, esm/translators, esm/load → TypeScript stripper / data: helpers: only for those inputs.
• pre_execution → internal/dns/utils: only for an explicit --dns-result-order (still validated at startup) or a snapshot build; 'verbatim' becomes the variable's initializer, so a snapshot-time setDefaultResultOrder() still survives deserialization.
• internal/worker → ELU / error_serdes on demand; worker_threads.locks via defineLazyProperties (as util does).

An intermediate version that didn't re-add these to the snapshot regressed node empty.mjs by 2–4 %, which is why the isBuildingSnapshot() block lists them explicitly. test-bootstrap-modules is adjusted for the worker-side list.

Tests: test-bootstrap-modules plus worker, url, fs, dns, process, cli, vm, snapshot, blob, esm, inspector, module, util, test-runner and single-executable suites pass.

---

Disclosure: the code, test, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

[nodejs-github-bot]

Review requested:

• @nodejs/loaders
• @nodejs/net
• @nodejs/startup
• @nodejs/url

[codecov]

Codecov Report

❌ Patch coverage is 66.66667% with 19 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.09%. Comparing base (30bff4a) to head (0cc532a).
⚠️ Report is 63 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/bootstrap/switches/is_main_thread.js	0.00%	18 Missing ⚠️
lib/internal/url.js	85.71%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65329      +/-   ##
==========================================
- Coverage   90.13%   90.09%   -0.05%     
==========================================
  Files         752      752              
  Lines      251568   252348     +780     
  Branches    47270    47462     +192     
==========================================
+ Hits       226759   227355     +596     
- Misses      16168    16292     +124     
- Partials     8641     8701      +60     

Files with missing lines	Coverage Δ
lib/fs.js	98.39% <100.00%> (+0.02%)	⬆️
lib/internal/dns/utils.js	100.00% <100.00%> (+0.55%)	⬆️
lib/internal/modules/cjs/loader.js	98.14% <100.00%> (ø)
lib/internal/modules/esm/load.js	91.32% <100.00%> (-0.08%)	⬇️
lib/internal/modules/esm/translators.js	97.56% <100.00%> (+0.01%)	⬆️
lib/internal/process/execution.js	94.76% <100.00%> (+0.21%)	⬆️
lib/internal/process/pre_execution.js	97.75% <100.00%> (+0.60%)	⬆️
lib/internal/worker.js	96.75% <100.00%> (-0.02%)	⬇️
lib/worker_threads.js	100.00% <100.00%> (ø)
lib/internal/url.js	93.28% <85.71%> (+0.01%)	⬆️
... and 1 more

... and 76 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/75905/

[github-actions]

Benchmark GHA (misc / startup-core): https://github.com/nodejs/node/actions/runs/32009241408

Results

[!WARNING]
Do not take GHA benchmark results as face value, always confirm them
using a dedicated machine, e.g. Jenkins CI.

Benchmark results:

                                                                                         confidence improvement accuracy (*)    (**)   (***)
misc/startup-core.js n=30 mode='process' script='benchmark/fixtures/empty.mjs'                           0.95 %      ±16.58% ±21.85% ±28.04%
misc/startup-core.js n=30 mode='process' script='benchmark/fixtures/import-builtins.mjs'                 0.60 %      ±11.57% ±15.25% ±19.56%
misc/startup-core.js n=30 mode='process' script='benchmark/fixtures/require-builtins.js'                 0.19 %      ±13.51% ±17.81% ±22.85%
misc/startup-core.js n=30 mode='process' script='test/fixtures/semicolon.js'                            -0.02 %      ±16.55% ±21.81% ±27.99%
misc/startup-core.js n=30 mode='process' script='test/fixtures/snapshot/typescript.js'                  -0.54 %       ±8.97% ±11.82% ±15.17%
misc/startup-core.js n=30 mode='worker' script='benchmark/fixtures/empty.mjs'                            3.74 %       ±9.02% ±11.89% ±15.26%
misc/startup-core.js n=30 mode='worker' script='benchmark/fixtures/import-builtins.mjs'                  1.08 %       ±8.87% ±11.69% ±15.00%
misc/startup-core.js n=30 mode='worker' script='benchmark/fixtures/require-builtins.js'                  1.37 %       ±8.86% ±11.67% ±14.98%
misc/startup-core.js n=30 mode='worker' script='test/fixtures/semicolon.js'                              4.08 %       ±9.20% ±12.13% ±15.56%
misc/startup-core.js n=30 mode='worker' script='test/fixtures/snapshot/typescript.js'                   -0.84 %       ±8.49% ±11.19% ±14.36%

Be aware that when doing many comparisons the risk of a false-positive
result increases. In this case, there are 10 comparisons, you can thus
expect the following amount of false-positive results:
  0.50 false positives, when considering a   5% risk acceptance (*, **, ***),
  0.10 false positives, when considering a   1% risk acceptance (**, ***),
  0.01 false positives, when considering a 0.1% risk acceptance (***)

[!WARNING]
Do not take GHA benchmark results as face value, always confirm them
using a dedicated machine, e.g. Jenkins CI.

[mcollina]

lgtm

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/75945/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/75963/

[aduh95]

The modified test is failing on Windows, indicating this PR is adding flakiness. Can you have a look?

---
duration_ms: 293.997
exitcode: 1
severity: fail
stack: |-
  node:internal/assert/utils:146
    throw error;
    ^

  AssertionError [ERR_ASSERTION]: These builtins are now no longer loaded before pre-execution.
  If this is intentional, remove them from `expected.beforePreExec`.

  --- These could be removed from expected.beforePreExec ---
  [
    'Internal Binding cjs_lexer',
    'Internal Binding encoding_binding',
    'NativeModule internal/blob',
    'NativeModule internal/data_url',
    'NativeModule internal/dns/utils',
    'NativeModule internal/encoding',
    'NativeModule internal/encoding/single-byte',
    'NativeModule internal/encoding/util',
    'NativeModule internal/mime',
    'NativeModule internal/modules/esm/assert',
    'NativeModule internal/modules/esm/get_format',
    'NativeModule internal/modules/esm/load',
    'NativeModule internal/modules/esm/loader',
    'NativeModule internal/modules/esm/module_job',
    'NativeModule internal/modules/esm/module_map',
    'NativeModule internal/modules/esm/resolve',
    'NativeModule internal/modules/esm/translators',
    'NativeModule internal/modules/typescript',
    'NativeModule internal/net',
    'NativeModule url'
  ]

  These builtins are now unexpectedly loaded at run time.
  If this is intentional, add them to `expected.atRunTime`.

  # Note: loading more builtins at run time can lead to startup performance regression.
  - Consider lazy loading builtins that are not used universally.

  --- These could be added to expected.atRunTime ---
  [
    'NativeModule internal/modules/esm/get_format'
  ]


  12 !== 0

      at Object.<anonymous> (d:\workspace\node-test-binary-windows-js-suites\node\test\parallel\test-bootstrap-modules.js:264:8)
      at Module._compile (node:internal/modules/cjs/loader:1937:14)
      at Module._extensions..js (node:internal/modules/cjs/loader:2077:10)
      at Module.load (node:internal/modules/cjs/loader:1659:32)
      at Module._load (node:internal/modules/cjs/loader:1451:12)
      at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
      at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
      at node:internal/main/run_main_module:33:47 {
    generatedMessage: false,
    code: 'ERR_ASSERTION',
    actual: 12,
    expected: 0,
    operator: 'strictEqual',
    diff: 'simple'
  }

  Node.js v27.0.0-pre
...

https://ci.nodejs.org/job/node-test-binary-windows-js-suites/42385/RUN_SUBSET=2,nodes=win11-arm64-COMPILED_BY-vs2022_clang-arm64/testReport/junit/(root)/parallel/test_bootstrap_modules/

[codebytere]

@aduh95 fixed!

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/76025/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/76043/

[codebytere]

@mcollina mind re-reviewing?

[joyeecheung]

I am in favor of "for snapshot less mode, try not to eager load that much" in general, although some of the removals seem somewhat too conservative (e.g. the url and util modules are commonly used by most applications) and may only favor the startup of empty scripts but penalise the startup of a real application that actually does something. So I think we should check the performance impact of the scripts that does something beyond being empty as well. If the number

misc/startup-core.js mode='process' (snapshot), all scripts                       ±0.5 %  n.s.

Comes from that scenario then LGTM, otherwise can you run the benchmark across the startup-core and startup-cli-version data sets?

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/76078/