Virtual File System for Node.js by mcollina · Pull Request #61478 · nodejs/node

mcollina · 2026-01-22T18:04:04Z

A first-class virtual file system module (node:vfs) with a provider-based architecture that integrates with Node.js's fs module and module loader.

Key Features

Provider Architecture - Extensible design with pluggable providers:
- MemoryProvider - In-memory file system with full read/write support
- SEAProvider - Read-only access to Single Executable Application assets
- VirtualProvider - Base class for creating custom providers
Standard fs API - Uses familiar writeFileSync, readFileSync, mkdirSync instead of custom methods
Mount Mode - VFS mounts at a specific path prefix (e.g., /virtual), clear separation from real filesystem
Module Loading - require() and import work seamlessly from virtual files
SEA Integration - Assets automatically mounted at /sea when running as a Single Executable Application
Full fs Support - readFile, stat, readdir, exists, streams, promises, glob, symlinks

Example

const vfs = require('node:vfs');
const fs = require('node:fs');

// Create a VFS with default MemoryProvider
const myVfs = vfs.create();

// Use standard fs-like API
myVfs.mkdirSync('/app');
myVfs.writeFileSync('/app/config.json', '{"debug": true}');
myVfs.writeFileSync('/app/module.js', 'module.exports = "hello"');

// Mount to make accessible via fs module
myVfs.mount('/virtual');

// Works with standard fs APIs
const config = JSON.parse(fs.readFileSync('/virtual/app/config.json', 'utf8'));
const mod = require('/virtual/app/module.js');

// Cleanup
myVfs.unmount();

SEA Usage

When running as a Single Executable Application, bundled assets are automatically available:

const fs = require('node:fs');

// Assets are automatically mounted at /sea - no setup required
const config = fs.readFileSync('/sea/config.json', 'utf8');
const template = fs.readFileSync('/sea/templates/index.html', 'utf8');

Public API

const vfs = require('node:vfs');

vfs.create([provider][, options])  // Create a VirtualFileSystem
vfs.VirtualFileSystem              // The main VFS class
vfs.VirtualProvider                // Base class for custom providers
vfs.MemoryProvider                 // In-memory provider
vfs.SEAProvider                    // SEA assets provider (read-only)

Disclaimer: I've used a significant amount of Claude Code tokens to create this PR. I've reviewed all changes myself.

Fixes #60021

nodejs-github-bot · 2026-01-22T18:04:09Z

Review requested:

@nodejs/single-executable
@nodejs/test_runner

github-actions · 2026-01-22T18:12:01Z

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @avivkeller.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

Ethan-Arrowood · 2026-01-22T18:44:11Z

Nice! This is a great addition. Since it's such a large PR, this will take me some time to review. Will try to tackle it over the next week.

avivkeller · 2026-01-22T18:12:30Z

lib/internal/test_runner/mock/mock.js

+   */
+  existsSync(path) {
+    // Prepend prefix to path for VFS lookup
+    const fullPath = this.#prefix + (StringPrototypeStartsWith(path, '/') ? path : '/' + path);


Can we use path.join?

lib/internal/test_runner/mock/mock.js

avivkeller · 2026-01-22T18:14:58Z

lib/internal/test_runner/mock/mock.js

+      validateObject(files, 'options.files');
+    }
+
+    const { VirtualFileSystem } = require('internal/vfs/virtual_fs');


Shouldn't we import this at the top level / lazy load it at the top level?

avivkeller · 2026-01-22T18:15:39Z

lib/internal/test_runner/mock/mock.js

+    ArrayPrototypePush(this.#mocks, {
+      __proto__: null,
+      ctx,
+      restore: restoreFS,


Suggested change

restore: restoreFS,

restore: ctx.restore,

nit

avivkeller · 2026-01-22T18:18:00Z

lib/internal/vfs/entries.js

+   * @param {object} [options] Optional configuration
+   */
+  addFile(name, content, options) {
+    const path = this._directory.path + '/' + name;


Can we use path.join?

avivkeller · 2026-01-22T18:43:10Z