vfs: add minimal node:vfs subsystem by mcollina · Pull Request #63115 · nodejs/node

mcollina · 2026-05-04T15:09:34Z

Adds an experimental node:vfs builtin (gated behind --experimental-vfs) with VirtualFileSystem, VirtualProvider, MemoryProvider, and RealFSProvider. No integration with node:fs, the module loader, or SEA those are intended to land in follow-up PRs.

Extracted from: #61478

Approximate line counts: code ~4k / docs ~1k / tests ~5k — total ~10k lines, with tests being the largest share.

nodejs-github-bot · 2026-05-04T15:09:40Z

Review requested:

@nodejs/config
@nodejs/loaders
@nodejs/startup

bakkot · 2026-05-04T18:37:03Z

No integration with node:fs

The docs in this PR claim that you can call myVfs.mount('/virtual') and subsequently regular node:fs operations which read from paths beginning with /virtual will read from the VFS. That sounds like integration to me. Are the docs wrong, or am I misunderstanding what "no integration" means?

mcollina · 2026-05-05T10:04:50Z

No integration with node:fs

The docs in this PR claim that you can call myVfs.mount('/virtual') and subsequently regular node:fs operations which read from paths beginning with /virtual will read from the VFS. That sounds like integration to me. Are the docs wrong, or am I misunderstanding what "no integration" means?

Fixed, good spot.

codecov · 2026-05-05T11:47:05Z

Codecov Report

❌ Patch coverage is 96.69092% with 191 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (131fd84) to head (1639c59).
⚠️ Report is 113 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/vfs/providers/memory.js	93.64%	61 Missing and 4 partials ⚠️
lib/internal/vfs/file_system.js	96.68%	38 Missing ⚠️
lib/internal/vfs/watcher.js	95.20%	32 Missing and 1 partial ⚠️
lib/internal/vfs/providers/real.js	96.01%	19 Missing ⚠️
lib/internal/vfs/streams.js	95.46%	16 Missing ⚠️
lib/internal/vfs/provider.js	98.38%	10 Missing ⚠️
lib/internal/vfs/file_handle.js	98.88%	7 Missing and 1 partial ⚠️
lib/internal/vfs/fd.js	97.70%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63115      +/-   ##
==========================================
- Coverage   91.94%   90.24%   -1.70%     
==========================================
  Files         362      726     +364     
  Lines      155999   231715   +75716     
  Branches    24057    43706   +19649     
==========================================
+ Hits       143429   209113   +65684     
- Misses      12295    14388    +2093     
- Partials      275     8214    +7939

Files with missing lines	Coverage Δ
lib/internal/bootstrap/realm.js	`96.28% <100.00%> (+0.69%)`	⬆️
lib/internal/modules/cjs/loader.js	`98.04% <100.00%> (+19.43%)`	⬆️
lib/internal/process/pre_execution.js	`98.28% <100.00%> (+15.17%)`	⬆️
lib/internal/vfs/dir.js	`100.00% <100.00%> (ø)`
lib/internal/vfs/errors.js	`100.00% <100.00%> (ø)`
lib/internal/vfs/stats.js	`100.00% <100.00%> (ø)`
lib/vfs.js	`100.00% <100.00%> (ø)`
src/node_builtins.cc	`76.32% <100.00%> (ø)`
src/node_options.cc	`76.65% <100.00%> (ø)`
src/node_options.h	`98.00% <100.00%> (ø)`
... and 8 more

... and 492 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 · 2026-05-06T08:07:49Z

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

nodejs-github-bot · 2026-05-07T06:23:28Z

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

aduh95 · 2026-05-07T08:29:20Z

Can you add a test for #63158?

nodejs-github-bot · 2026-05-18T09:28:34Z

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

aduh95 · 2026-05-18T13:46:41Z

+  let data = '';
+
+  stream.on('open', common.mustCall((fd) => {
+    assert.ok((fd & 0x40000000) !== 0);


Suggested change

assert.ok((fd & 0x40000000) !== 0);

assert.notStrictEqual(fd & 0x40000000, 0);

aduh95 · 2026-05-18T13:48:45Z

+  ws.on('error', common.mustCall((err) => {
+    assert.ok(err);
+  }));


Suggested change

ws.on('error', common.mustCall((err) => {

assert.ok(err);

}));

ws.on('error', common.expectsError());

aduh95 · 2026-05-18T13:49:10Z

+  ws.on('error', common.mustCall((err) => {
+    assert.ok(err);
+  }));


Suggested change

ws.on('error', common.mustCall((err) => {

assert.ok(err);

}));

ws.on('error', common.expectsError());

aduh95 · 2026-05-18T13:49:43Z

+  const fd = myVfs.openSync('/cl.txt');
+  const rs = myVfs.createReadStream('/cl.txt', { fd, autoClose: true });
+  myVfs.closeSync(fd);
+  rs.on('error', common.mustCall());


Suggested change

rs.on('error', common.mustCall());

rs.on('error', common.expectsError());

aduh95 · 2026-05-18T13:50:32Z

+  rs.on('error', common.mustCall((err) => {
+    assert.strictEqual(err.code, 'EBADF');
+  }));


Suggested change

rs.on('error', common.mustCall((err) => {

assert.strictEqual(err.code, 'EBADF');

}));

rs.on('error', common.expectsError({

code: 'EBADF',

}));

aduh95 · 2026-05-18T13:50:47Z

+  stream.on('error', common.mustCall((err) => {
+    assert.strictEqual(err.code, 'ENOENT');
+  }));


Suggested change

stream.on('error', common.mustCall((err) => {

assert.strictEqual(err.code, 'ENOENT');

}));

stream.on('error', common.expectsError({

code: 'ENOENT',

}));

Co-authored-by: Antoine du Hamel <[email protected]> Co-authored-by: Matteo Collina <[email protected]>

* test-vfs-stream-errors: drop the unused `assert` import. * test-vfs-streams: capitalize a lowercase comment to satisfy capitalized-comments. Signed-off-by: Matteo Collina <[email protected]>

Co-authored-by: Antoine du Hamel <[email protected]>

spawnSyncAndAssert handles the expected stderr/status, so the top-level `assert` is no longer referenced. Signed-off-by: Matteo Collina <[email protected]>

nodejs-github-bot · 2026-05-19T20:37:02Z

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

Signed-off-by: Matteo Collina <[email protected]>

Qard

LGTM. Some minor improvements which could be made, but nothing which needs to block landing. 🙂

ShogunPanda

LGTM!

nodejs-github-bot · 2026-05-21T13:51:03Z

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

The currentPath segment used for symlink resolution and for the #ensurePopulated call below was being computed twice in the loop body. Compute it once at the top of the iteration and reuse it in both branches. Signed-off-by: Matteo Collina <[email protected]>

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 4, 2026

jasnell approved these changes May 4, 2026

View reviewed changes

mcollina force-pushed the vfs-minimal branch 2 times, most recently from 30f5755 to 779fc37 Compare May 5, 2026 09:30

mcollina marked this pull request as ready for review May 5, 2026 10:04

ShogunPanda approved these changes May 5, 2026

View reviewed changes

ShogunPanda approved these changes May 6, 2026

View reviewed changes

mcollina added help wanted Issues that need assistance from volunteers or PRs that need help to proceed. request-ci Add this label to start a Jenkins CI on a PR. labels May 6, 2026

mcollina mentioned this pull request May 6, 2026

Virtual File System for Node.js #61478

Open

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

ronag approved these changes May 6, 2026

View reviewed changes

ShogunPanda approved these changes May 7, 2026

View reviewed changes

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

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

aduh95 reviewed May 7, 2026

View reviewed changes

Comment thread doc/api/vfs.md Outdated

aduh95 reviewed May 7, 2026

View reviewed changes

Comment thread doc/api/vfs.md Outdated

aduh95 reviewed May 7, 2026

View reviewed changes

Comment thread lib/internal/bootstrap/realm.js Outdated

mcollina force-pushed the vfs-minimal branch from de4882c to cb420d9 Compare May 11, 2026 06:53

ShogunPanda approved these changes May 11, 2026

View reviewed changes

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

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

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

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