lib: load fewer builtins when bootstrapping without a snapshot by codebytere · Pull Request #65329 · nodejs/node · GitHub

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.

Review requested:

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

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 105 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.

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

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.

lgtm

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

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

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/

@aduh95 fixed!

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

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

@mcollina mind re-reviewing?

Contexts that are not deserialized from the built-in snapshot -- worker threads, and the main context of embedders that create their own isolate or of `node --no-node-snapshot` -- compile (with the code cache at best) every builtin the bootstrap touches, so each eagerly required builtin is startup time (~0.15-0.4 ms apiece). A number of them are only required eagerly so that they end up in the snapshot, or for features the bootstrap path never uses. Load lazily what those paths do not need: - is_main_thread.js: preload util, url, the ESM loader (translators, resolver, module_job/map, source maps, node:module, vm modules, mime, data_url, the TypeScript stripper), internal/blob and internal/dns/utils only while building a snapshot; they load on first use otherwise. - fs: internal/blob (+ internal/encoding and its tables) is only used by fs.openAsBlob(). - internal/url: internal/data_url (+ internal/mime) is only used by the Buffer-returning file URL helpers. - internal/process/execution, the CommonJS loader, esm/translators and esm/load: the TypeScript stripper and data: URL helpers are only needed for TypeScript sources / data: URLs. - pre_execution: internal/dns/utils (+ internal/net) is only needed up front to validate an explicit --dns-result-order or to register the resolver's snapshot serializer; the default order becomes the variable's initializer. - internal/worker: event_loop_utilization and error_serdes are only needed once a sub-worker's ELU is read or it reports an error. - worker_threads: `locks` is defined lazily, like util's lazy exports. Main-thread startup with the snapshot is unchanged (the same modules are preloaded into it; the bootstrap-modules test lists are adjusted). A bare worker compiles 95 -> 83 builtins (cold start -5%); without the snapshot an empty CommonJS entry point compiles 76 -> 59 builtins and an empty ES module entry point 76 -> 69. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

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?

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

@joyeecheung yes, that row is startup-core mode=process with the snapshot, all five scripts including require-builtins.js and import-builtins.mjs; the benchmark CI run above (https://github.com/nodejs/node/actions/runs/32009241408) shows the same on all four machines: process rows within ±1 % n.s., worker rows +1…5 %.

for the "app that actually does something" case i ran startup-cli-version and a builtin-heavy entry point both with the snapshot and with --no-node-snapshot (n=30, linux x64):

                                               with snapshot     --no-node-snapshot
startup-cli-version  eslint --version         -0.14 %  n.s.     +1.70 %  ***
                     npm --version            -0.00 %  n.s.     +0.69 %  ***
                     npx --version            +0.11 %  n.s.     +0.80 %  **
                     corepack --version       -0.19 %  n.s.     +3.21 %  ***
require-builtins.js (start -> exit)           -0.08 %  n.s.     +1.97 %  ***
import-builtins.mjs                           +0.19 %  n.s.     +0.13 %  n.s.
empty CJS entry                               +0.04 %  n.s.    +10.59 %  ***

so nothing gets penalized: with the snapshot the preloaded set is unchanged (they sit behind isBuildingSnapshot() rather than being removed), and without it util/url/the esm loader are loaded on first require at the same cost as before, just not up front for entry points that never touch them. the win shrinks as the app uses more of core, as you'd expect, but it doesn't go negative.

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

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

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

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

Landed in e38eede

Contexts that are not deserialized from the built-in snapshot -- worker threads, and the main context of embedders that create their own isolate or of `node --no-node-snapshot` -- compile (with the code cache at best) every builtin the bootstrap touches, so each eagerly required builtin is startup time (~0.15-0.4 ms apiece). A number of them are only required eagerly so that they end up in the snapshot, or for features the bootstrap path never uses. Load lazily what those paths do not need: - is_main_thread.js: preload util, url, the ESM loader (translators, resolver, module_job/map, source maps, node:module, vm modules, mime, data_url, the TypeScript stripper), internal/blob and internal/dns/utils only while building a snapshot; they load on first use otherwise. - fs: internal/blob (+ internal/encoding and its tables) is only used by fs.openAsBlob(). - internal/url: internal/data_url (+ internal/mime) is only used by the Buffer-returning file URL helpers. - internal/process/execution, the CommonJS loader, esm/translators and esm/load: the TypeScript stripper and data: URL helpers are only needed for TypeScript sources / data: URLs. - pre_execution: internal/dns/utils (+ internal/net) is only needed up front to validate an explicit --dns-result-order or to register the resolver's snapshot serializer; the default order becomes the variable's initializer. - internal/worker: event_loop_utilization and error_serdes are only needed once a sub-worker's ELU is read or it reports an error. - worker_threads: `locks` is defined lazily, like util's lazy exports. Main-thread startup with the snapshot is unchanged (the same modules are preloaded into it; the bootstrap-modules test lists are adjusted). A bare worker compiles 95 -> 83 builtins (cold start -5%); without the snapshot an empty CommonJS entry point compiles 76 -> 59 builtins and an empty ES module entry point 76 -> 69. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com> PR-URL: #65329 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Aviv Keller <me@aviv.sh>

nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Aug 16, 2026

codebytere requested review from jasnell and joyeecheung August 16, 2026 16:44

codebytere added request-ci Add this label to start a Jenkins CI on a PR. and removed needs-ci PRs that need a full CI run. labels Aug 16, 2026

jasnell approved these changes Aug 17, 2026

View reviewed changes

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Aug 17, 2026

codebytere force-pushed the perf/bootstrap-fewer-builtins-without-snapshot branch from 5d49228 to 088f769 Compare August 17, 2026 08:01

targos added the needs-benchmark-ci PR that need a benchmark CI run. label Aug 17, 2026

aduh95 approved these changes Aug 17, 2026

View reviewed changes

mcollina approved these changes Aug 17, 2026

View reviewed changes

codebytere added request-ci Add this label to start a Jenkins CI on a PR. and removed needs-benchmark-ci PR that need a benchmark CI run. labels Aug 17, 2026

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Aug 17, 2026

codebytere force-pushed the perf/bootstrap-fewer-builtins-without-snapshot branch from 088f769 to 0d3b8a7 Compare August 18, 2026 09:18

nodejs deleted a comment from codebytere-ant Aug 18, 2026

aduh95 reviewed Aug 18, 2026

View reviewed changes

Comment thread test/parallel/test-bootstrap-modules.js Outdated

codebytere force-pushed the perf/bootstrap-fewer-builtins-without-snapshot branch from 0d3b8a7 to f95b3c7 Compare August 18, 2026 14:13

codebytere requested review from aduh95, jasnell and mcollina August 19, 2026 08:52

codebytere added the request-ci Add this label to start a Jenkins CI on a PR. label Aug 19, 2026

jasnell approved these changes Aug 20, 2026

View reviewed changes

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Aug 20, 2026

aduh95 reviewed Aug 20, 2026

View reviewed changes

Comment thread test/parallel/test-bootstrap-modules.js Outdated

aduh95 reviewed Aug 20, 2026

View reviewed changes

Comment thread test/parallel/test-bootstrap-modules.js Outdated

codebytere force-pushed the perf/bootstrap-fewer-builtins-without-snapshot branch from f95b3c7 to 0cc532a Compare August 20, 2026 12:39

codebytere added the request-ci Add this label to start a Jenkins CI on a PR. label Aug 20, 2026

legendecas approved these changes Aug 20, 2026

View reviewed changes

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Aug 20, 2026

avivkeller approved these changes Aug 21, 2026

View reviewed changes

codebytere added the commit-queue Add this label to land a pull request using GitHub Actions. label Aug 22, 2026

nodejs-github-bot merged commit e38eede into nodejs:main Aug 22, 2026
71 checks passed

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Aug 22, 2026

github-actions Bot mentioned this pull request Aug 25, 2026

2026-08-26, Version 26.8.0 (Current) #65551

Open

lib: load fewer builtins when bootstrapping without a snapshot by codebytere · Pull Request #65329 · nodejs/node · GitHub

Uh oh!

Uh oh!

lib: load fewer builtins when bootstrapping without a snapshot - #65329

lib: load fewer builtins when bootstrapping without a snapshot#65329nodejs-github-bot merged 1 commit intonodejs:mainnodejs/node:mainfrom codebytere:perf/bootstrap-fewer-builtins-without-snapshotcodebytere/node:perf/bootstrap-fewer-builtins-without-snapshotCopy head branch name to clipboard

Conversation

codebytere commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Aug 16, 2026

Uh oh!

codecov Bot commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

nodejs-github-bot commented Aug 17, 2026

Uh oh!

github-actions Bot commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Aug 17, 2026

Uh oh!

nodejs-github-bot commented Aug 18, 2026

Uh oh!

aduh95 commented Aug 18, 2026

Uh oh!

codebytere commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

nodejs-github-bot commented Aug 20, 2026

Uh oh!

nodejs-github-bot commented Aug 20, 2026

Uh oh!

codebytere commented Aug 20, 2026

Uh oh!

Uh oh!

Uh oh!

joyeecheung commented Aug 20, 2026

Uh oh!

nodejs-github-bot commented Aug 20, 2026

Uh oh!

codebytere commented Aug 21, 2026

Uh oh!

nodejs-github-bot commented Aug 21, 2026

Uh oh!

nodejs-github-bot commented Aug 21, 2026

Uh oh!

nodejs-github-bot commented Aug 21, 2026

Uh oh!

nodejs-github-bot commented Aug 22, 2026

Uh oh!

Uh oh!

nodejs-github-bot commented Aug 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

lib: load fewer builtins when bootstrapping without a snapshot#65329
nodejs-github-bot merged 1 commit into
nodejs:mainfrom
codebytere:perf/bootstrap-fewer-builtins-without-snapshot

codebytere commented Aug 16, 2026 •
edited
Loading

codecov Bot commented Aug 16, 2026 •
edited
Loading

github-actions Bot commented Aug 17, 2026 •
edited
Loading

codebytere commented Aug 18, 2026 •
edited
Loading