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.69149% with 191 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.31%. Comparing base (8d3245e) to head (1088e5f).
⚠️ Report is 5 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   90.14%   90.31%   +0.16%     
==========================================
  Files         718      730      +12     
  Lines      227984   233756    +5772     
  Branches    42835    43803     +968     
==========================================
+ Hits       205522   211121    +5599     
- Misses      14235    14400     +165     
- Partials     8227     8235       +8

Files with missing lines	Coverage Δ
lib/internal/bootstrap/realm.js	`96.29% <100.00%> (+0.06%)`	⬆️
lib/internal/modules/cjs/loader.js	`98.05% <100.00%> (+<0.01%)`	⬆️
lib/internal/process/pre_execution.js	`97.93% <100.00%> (+0.14%)`	⬆️
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.37% <100.00%> (+0.23%)`	⬆️
src/node_options.cc	`76.67% <100.00%> (+0.02%)`	⬆️
src/node_options.h	`98.00% <100.00%> (+<0.01%)`	⬆️
... and 8 more

... and 36 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?

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com> Co-authored-by: Matteo Collina <matteo.collina@gmail.com>

* 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 <hello@matteocollina.com>

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>

spawnSyncAndAssert handles the expected stderr/status, so the top-level `assert` is no longer referenced. Signed-off-by: Matteo Collina <hello@matteocollina.com>

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

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 <hello@matteocollina.com>

nodejs-github-bot · 2026-05-23T13:39:46Z

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

nodejs-github-bot · 2026-05-23T16:57:39Z

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

nodejs-github-bot · 2026-05-23T18:43:33Z

Landed in c9562dd

Add mount/unmount lifecycle on `VirtualFileSystem`, a handler registry that fs.js and fs/promises.js consult via `vfsState.handlers`, and a router that maps absolute paths to the VFS that owns them. When a VFS is mounted, the public `fs.*` and `fs/promises` APIs (including streams, `fs.watch`, and `opendir`) dispatch to the provider for paths under the mount point, and fall through to the real filesystem otherwise. Includes per-method dispatch tests, error-path coverage, multi-mount routing tests, and router unit tests. Ref: nodejs#63115 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Adds the node:vfs builtin module with VirtualFileSystem and provider classes. No integration with fs, modules, or SEA. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com> PR-URL: nodejs#63115 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Robert Nagy <ronagy@icloud.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>

Add mount/unmount lifecycle on `VirtualFileSystem`, a handler registry that fs.js and fs/promises.js consult via `vfsState.handlers`, and a router that maps absolute paths to the VFS that owns them. When a VFS is mounted, the public `fs.*` and `fs/promises` APIs (including streams, `fs.watch`, and `opendir`) dispatch to the provider for paths under the mount point, and fall through to the real filesystem otherwise. Includes per-method dispatch tests, error-path coverage, multi-mount routing tests, and router unit tests. Ref: nodejs#63115 Signed-off-by: Matteo Collina <hello@matteocollina.com>

Add mount/unmount lifecycle on `VirtualFileSystem`, a handler registry that fs.js and fs/promises.js consult via `vfsState.handlers`, and a router that maps absolute paths to the VFS that owns them. When a VFS is mounted, the public `fs.*` and `fs/promises` APIs (including streams, `fs.watch`, and `opendir`) dispatch to the provider for paths under the mount point, and fall through to the real filesystem otherwise. Includes per-method dispatch tests, error-path coverage, multi-mount routing tests, and router unit tests. Ref: #63115 Signed-off-by: Matteo Collina <hello@matteocollina.com> PR-URL: #63537 Refs: #63115 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it>

The original draft was ported from @platformatic/vfs (extracted from the still-open nodejs/node#61478). Node has since merged the experimental subsystem in nodejs/node#63115, with a slightly different public surface. Rebase the polyfill on the merged source so the API matches what landed in Node behind --experimental-vfs: - Stats objects are now real fs.Stats / BigIntStats instances (no more custom VirtualStats shape). - Adds RealFSProvider, VirtualDir, plus the polling watcher classes (VFSWatcher / VFSStatWatcher / VFSWatchAsyncIterable). - Adds rmSync/rm, truncateSync, linkSync, chmodSync, chownSync, utimesSync, lutimesSync, mkdtempSync, opendirSync, openAsBlob, the matching callback wrappers, and the matching promises API. - Drops the Deno-specific extensions from the previous draft (mount/unmount/mounted/shouldHandle, virtualCwd/chdir, vfs-mount and vfs-unmount process events, internalModuleStat); they have no counterpart in the merged Node API and the module-loader integration is intentionally left for a follow-up upstream. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Adds the node:vfs builtin module with VirtualFileSystem and provider classes. No integration with fs, modules, or SEA. Assisted-by: Claude-Opus4.7 Signed-off-by: Matteo Collina <hello@matteocollina.com> PR-URL: #63115 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Robert Nagy <ronagy@icloud.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>

Add mount/unmount lifecycle on `VirtualFileSystem`, a handler registry that fs.js and fs/promises.js consult via `vfsState.handlers`, and a router that maps absolute paths to the VFS that owns them. When a VFS is mounted, the public `fs.*` and `fs/promises` APIs (including streams, `fs.watch`, and `opendir`) dispatch to the provider for paths under the mount point, and fall through to the real filesystem otherwise. Includes per-method dispatch tests, error-path coverage, multi-mount routing tests, and router unit tests. Ref: #63115 Signed-off-by: Matteo Collina <hello@matteocollina.com> PR-URL: #63537 Refs: #63115 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it>

Notable changes: build, doc: * generate node.1 with doc-kit (Aviv Keller) #62044 deps: * (SEMVER-MINOR) update OpenSSL build config to support compression (Tim Perry) #62217 doc: * (SEMVER-MINOR) update `blockList` stability status to release candidate (alphaleadership) #63050 fs: * (SEMVER-MINOR) support caller-supplied readFile() buffers (Matteo Collina) #63634 http: * (SEMVER-MINOR) close pre-request sockets in closeIdleConnections (semimikoh) #63470 loader: * (SEMVER-MINOR) implement package maps (Maël Nison) #62239 net: * (SEMVER-MINOR) support TCP_KEEPINTVL and TCP_KEEPCNT in setKeepAlive (Guy Bedford) #63825 tls: * (SEMVER-MINOR) add certificateCompression option (Tim Perry) #62217 vfs: * (SEMVER-MINOR) dispatch fs/promises to mounted VFS instances (Matteo Collina) #63537 * (SEMVER-MINOR) add minimal node:vfs subsystem (Matteo Collina) #63115 PR-URL: #64058

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 and others added 6 commits May 23, 2026 15:11

Apply suggestions from code review

a2a6566

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com> Co-authored-by: Matteo Collina <matteo.collina@gmail.com>

test: fix lint errors in vfs stream tests

c6dd379

* 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 <hello@matteocollina.com>

Apply suggestions from code review

82e79d1

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>

test: drop unused assert import in test-vfs-flag

e105526

spawnSyncAndAssert handles the expected stderr/status, so the top-level `assert` is no longer referenced. Signed-off-by: Matteo Collina <hello@matteocollina.com>

fixup

e0a66b4

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

mcollina force-pushed the vfs-minimal branch from 1639c59 to 1088e5f Compare May 23, 2026 13:18

ShogunPanda approved these changes May 23, 2026

View reviewed changes

jasnell approved these changes May 23, 2026

View reviewed changes

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

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

mcollina added commit-queue Add this label to land a pull request using GitHub Actions. commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. labels May 23, 2026

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

nodejs-github-bot merged commit c9562dd into nodejs:main May 23, 2026
77 checks passed

mcollina mentioned this pull request May 24, 2026

vfs: dispatch fs/promises to mounted VFS instances #63537

Merged

littledivy mentioned this pull request Jun 2, 2026

feat(ext/node): add experimental node:vfs polyfill denoland/deno#34644

Closed

5 tasks

github-actions Bot mentioned this pull request Jun 22, 2026

2026-06-23, Version 26.4.0 (Current) #64058

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

vfs: add minimal node:vfs subsystem#63115

vfs: add minimal node:vfs subsystem#63115
nodejs-github-bot merged 32 commits into
nodejs:mainfrom
mcollina:vfs-minimal

mcollina commented May 4, 2026 •

edited

Loading

Uh oh!

nodejs-github-bot commented May 4, 2026

Uh oh!

bakkot commented May 4, 2026

Uh oh!

mcollina commented May 5, 2026

Uh oh!

codecov Bot commented May 5, 2026 •

edited

Loading

Uh oh!

nodejs-github-bot commented May 6, 2026

Uh oh!

nodejs-github-bot commented May 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aduh95 commented May 7, 2026

Uh oh!

nodejs-github-bot commented May 23, 2026

Uh oh!

nodejs-github-bot commented May 23, 2026

Uh oh!

Uh oh!

nodejs-github-bot commented May 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

Uh oh!

Conversation

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

Uh oh!

Uh oh!

nodejs-github-bot commented May 4, 2026

Uh oh!

bakkot commented May 4, 2026

Uh oh!

mcollina commented May 5, 2026

Uh oh!

codecov Bot commented May 5, 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 May 6, 2026

Uh oh!

nodejs-github-bot commented May 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aduh95 commented May 7, 2026

Uh oh!

nodejs-github-bot commented May 23, 2026

Uh oh!

nodejs-github-bot commented May 23, 2026

Uh oh!

Uh oh!

nodejs-github-bot commented May 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

mcollina commented May 4, 2026 •

edited

Loading

codecov Bot commented May 5, 2026 •

edited

Loading