vfs: integrate with CJS and ESM module loaders by mcollina · Pull Request #63653 · nodejs/node

mcollina · 2026-05-30T05:41:48Z

Makes require() and import resolve files served by node:vfs. Before this PR, mounted VFS files were only visible through fs.*; the loaders went straight to the real filesystem.

Design

vfs.mount() takes no arguments and returns the reserved absolute mount point of the instance: ${os.devNull}/vfs/<layerId> (for example /dev/null/vfs/0). os.devNull is a character device on POSIX and a device-namespace path on Windows; neither can have child filesystem entries, so no real path can ever exist under this root.

Everything about ownership is decidable from the path alone:

Dispatch: one path normalization, one prefix comparison against the namespace root, one map lookup on the layer id. O(1) in the number of mounted layers — the benchmark (benchmark/vfs/bench-fs-dispatch.js) reports flat per-call latency across 1..10 mounted layers.
Real-fs paths short-circuit with a single prefix check.
Unmount purges loader caches by prefix-scanning the mount point — no per-VFS ownership tracking is needed, and no other-VFS or real-fs entries are ever touched.
Symlink correctness: realpathSync of a VFS entry always resolves to another path under the same mount point, so cache entries hidden behind symlinks are captured by the prefix scan.
Dynamic-import identity: resolved URLs are plain file: URLs under the mount point; import(import.meta.resolve(x)) re-hits the same module job.

Two instances mounting simultaneously never collide (each gets its own layer-<id> segment), so there is no overlap validation and no ordering hazard between mounts.

Loader integration

Toggleable wrappers in the loaders. Null fast-path when no VFS is mounted; otherwise the VFS answers stat / readFile / realpath / legacyMainResolve / getFormatOfExtensionlessFile and the four package.json C++-binding calls.

Module identity follows the path: __filename, module.filename, and import.meta.url are the plain absolute path (or file: URL) of the module under the mount point — no synthetic decorations.

Review guide

Refs

The reserved-namespace design follows the "no interference with valid paths in the file system" requirement from the SEA VFS requirements doc.

Out of scope

SEA + VFS, overlay/stacking of multiple VFS layers under one prefix, migrating the C++ package_configs_ cache, broader permission-model integration.

nodejs-github-bot · 2026-05-30T05:41:54Z

Review requested:

@nodejs/loaders

codecov · 2026-05-30T06:50:02Z

Codecov Report

❌ Patch coverage is 92.03233% with 69 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.33%. Comparing base (967d4af) to head (46afd4e).
⚠️ Report is 10 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/vfs/setup.js	88.57%	48 Missing ⚠️
src/node_modules.cc	77.96%	4 Missing and 9 partials ⚠️
lib/internal/modules/cjs/loader.js	90.00%	4 Missing ⚠️
lib/internal/vfs/file_system.js	97.18%	2 Missing ⚠️
lib/internal/vfs/router.js	96.42%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main   #63653    +/-   ##
========================================
  Coverage   90.32%   90.33%            
========================================
  Files         751      751            
  Lines      249962   250496   +534     
  Branches    47210    47345   +135     
========================================
+ Hits       225783   226280   +497     
- Misses      15570    15599    +29     
- Partials     8609     8617     +8

Files with missing lines	Coverage Δ
lib/fs.js	`98.37% <100.00%> (+<0.01%)`	⬆️
lib/internal/modules/esm/get_format.js	`95.20% <100.00%> (ø)`
lib/internal/modules/esm/load.js	`91.40% <100.00%> (ø)`
lib/internal/modules/esm/resolve.js	`99.02% <100.00%> (-0.04%)`	⬇️
lib/internal/modules/helpers.js	`98.73% <100.00%> (-0.20%)`	⬇️
lib/internal/modules/package_json_reader.js	`99.48% <100.00%> (+0.03%)`	⬆️
lib/internal/modules/run_main.js	`97.64% <100.00%> (ø)`
src/node_modules.h	`100.00% <ø> (ø)`
lib/internal/vfs/file_system.js	`99.69% <97.18%> (+0.31%)`	⬆️
lib/internal/vfs/router.js	`97.46% <96.42%> (-0.36%)`	⬇️
... and 3 more

... and 33 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.

mcollina · 2026-05-30T10:27:16Z

@joyeecheung take a look, should be easier to review.

nodejs-github-bot · 2026-06-03T08:04:09Z

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

nodejs-github-bot · 2026-06-03T11:52:41Z

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

joyeecheung

A design question recently occurred to me: have we explored the versioning of the mounting?

mcollina · 2026-06-03T12:40:18Z

A design question recently occurred to me: have we explored the versioning of the mounting?

what do you mean? You mean multiple vfs layers on top of each other?

joyeecheung · 2026-06-03T13:02:48Z

what do you mean? You mean multiple vfs layers on top of each other?

For the stacks to have some kind of version number/ID to identify the current status?

BTW I just noticed that there's no mention of unmount() and mount() in the VFS docs..

mcollina · 2026-06-03T20:10:47Z

BTW I just noticed that there's no mention of unmount() and mount() in the VFS docs..

I did purge them when doing the splitting; I forgot to bring them back. I'll add them to this PR.

mcollina · 2026-06-03T20:11:45Z

For the stacks to have some kind of version number/ID to identify the current status?

No but we totally should.

mcollina · 2026-06-05T06:47:09Z

@joyeecheung PTAL

Signed-off-by: Matteo Collina <hello@matteocollina.com>

This reverts commit a95717a.

Signed-off-by: Matteo Collina <hello@matteocollina.com>

Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com>

The microbenchmark drove 1000+ iterations to reach the optimizing tier, which is not representative of real workloads. Module-loading against a mounted VFS is the meaningful signal and can be measured with the existing benchmark harness.

Measures loading a large CJS or ESM module graph from a mounted VFS, relying on the unmount cache purge so every iteration is a cold load.

Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com>

nodejs-github-bot · 2026-08-14T21:40:23Z

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

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 May 30, 2026

mcollina requested review from ShogunPanda, jasnell and joyeecheung May 30, 2026 10:26

ShogunPanda approved these changes May 30, 2026

View reviewed changes

jsumners-nr reviewed Jun 1, 2026

View reviewed changes

Comment thread lib/internal/modules/esm/load.js Outdated

Comment thread lib/internal/modules/esm/resolve.js Outdated

mcollina force-pushed the vfs-module-loader-integration branch from 6321e08 to 51b033a Compare June 1, 2026 15:54

ShogunPanda approved these changes Jun 2, 2026

View reviewed changes

mcollina added the request-ci Add this label to start a Jenkins CI on a PR. label Jun 3, 2026

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

joyeecheung reviewed Jun 3, 2026

View reviewed changes

Comment thread lib/internal/vfs/setup.js Outdated

mcollina force-pushed the vfs-module-loader-integration branch from 51b033a to 294a19c Compare June 4, 2026 07:23

coderabbitai Bot mentioned this pull request Jun 12, 2026

build: migrate from Workers to Docker jsdelivr/globalping-dash#204

Merged

arcanis mentioned this pull request Jun 15, 2026

module: add --experimental-strip-private-modules #63869

Open

ShogunPanda approved these changes Jun 15, 2026

View reviewed changes

mcollina force-pushed the vfs-module-loader-integration branch from 75bb5c7 to 99a5a5c Compare June 15, 2026 09:00

mcollina and others added 28 commits August 14, 2026 18:40

vfs: return normalized path from findVFS

0ea9687

Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs: inline isUnderMountPoint and use shouldHandleNormalized

f268b48

Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs,esm: share legacyMainResolveExtensions arrays

8f8ce91

Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs: add cleanForVfsPrefix helper for cache purges

853b70e

Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs: use indexed for loops in cleanForVfsPrefix

eda542f

Signed-off-by: Matteo Collina <hello@matteocollina.com>

Revert "vfs: use indexed for loops in cleanForVfsPrefix"

7c0772a

This reverts commit a95717a.

vfs: fold loader wrappers into wrapLoaderMethod factory

ccedaa6

Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs: fix lint on wrapLoaderMethod curly braces

06dfa3e

Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs: throw ERR_INVALID_PACKAGE_CONFIG on malformed ancestor pjson

c99a4c7

Signed-off-by: Matteo Collina <hello@matteocollina.com>

src: split GetPackageJSON and expose parsePackageJSON binding

3919029

Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs: use native parsePackageJSON binding, drop serializePackageJSON

aa18cde

Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs: read pjson as Buffer, skip UTF-8 decode

eee68d3

Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs: strip verbose comments across the PR

1fa9dd0

Signed-off-by: Matteo Collina <hello@matteocollina.com>

vfs: unexpose layerId property

fb5b8aa

Signed-off-by: Matteo Collina <hello@matteocollina.com>

Update doc/api/vfs.md

ef43d53

Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com>

benchmark: remove vfs fs-dispatch microbenchmark

7ba527d

The microbenchmark drove 1000+ iterations to reach the optimizing tier, which is not representative of real workloads. Module-loading against a mounted VFS is the meaningful signal and can be measured with the existing benchmark harness.

benchmark: add vfs module-graph cold-load benchmark

9177402

Measures loading a large CJS or ESM module graph from a mounted VFS, relying on the unmount cache purge so every iteration is a cold load.

doc: remove unused os.devNull link definition

25ffe98

doc: specify vfs precedence in module resolution

94ec8c1

Update doc/api/vfs.md

9469bd2

Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com>

vfs: restore jsdoc removed in comment cleanup

0cbf934

vfs: name loader hooks after the methods they wrap

225e7b5

vfs: add mountPointURL property

bc2dff0

vfs: return string from mountPointURL

7aefe08

vfs: key loader overrides by method name

b4d36dc

vfs: stop node_modules lookup at the mount point

08fdce5

doc: make vfs module lookup list exact

5ec10ae

test: adapt vfs lchown test to reserved mounts

46afd4e

mcollina force-pushed the vfs-module-loader-integration branch from 27f2214 to 46afd4e Compare August 14, 2026 19:11

#	File	Role
1	`lib/internal/vfs/router.js`	Reserved-namespace helpers: `getVfsRoot`, `getLayerRoot`, `getLayerIdFromPath`.
2	`lib/internal/vfs/file_system.js`	`mount()` returns the layer's reserved mount point.
3	`lib/internal/vfs/setup.js`	Heart of the PR. `findVFS` (O(1) lookup), fs handler, loader overrides with parity to `src/node_modules.cc` / `src/node_file.cc`, prefix-scan cache purge.
4	`lib/internal/modules/helpers.js`	Hook surface: `loader*` wrappers, `setLoaderFsOverrides` / `setLoaderPackageOverrides`, `purgeRealpathCacheForPrefix`.
5	`lib/internal/modules/cjs/loader.js`	`stat()` + TS read routed through wrappers; `purgeModuleCachesForPrefix` for unmount.
6	`lib/internal/modules/esm/resolve.js`	`legacyMainResolve` + `internalModuleStat` + `toRealPath` routed. No URL decoration.
7	`lib/internal/modules/esm/load.js`	`getSourceSync` reads via the wrapper.
8	`lib/internal/modules/esm/get_format.js`	Extensionless format detection routed.
9	`lib/internal/modules/package_json_reader.js`	4 C++ binding calls routed; `purgePackageJSONCacheForPrefix`.
10	`lib/fs.js`	`statSync` / `lstatSync` honour `throwIfNoEntry:false` on ENOENT from the VFS handler.
11	`doc/api/vfs.md`	Mount semantics + Module loader integration section.

Uh oh!

Uh oh!

Conversation

mcollina commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Design

Loader integration

Review guide

Refs

Out of scope

Uh oh!

nodejs-github-bot commented May 30, 2026

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

mcollina commented May 30, 2026

Uh oh!

Uh oh!

Uh oh!

nodejs-github-bot commented Jun 3, 2026

Uh oh!

nodejs-github-bot commented Jun 3, 2026

Uh oh!

joyeecheung left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mcollina commented Jun 3, 2026

Uh oh!

joyeecheung commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcollina commented Jun 3, 2026

Uh oh!

mcollina commented Jun 3, 2026

Uh oh!

mcollina commented Jun 5, 2026

Uh oh!

nodejs-github-bot commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

mcollina commented May 30, 2026 •

edited

Loading

codecov Bot commented May 30, 2026 •

edited

Loading

joyeecheung commented Jun 3, 2026 •

edited

Loading