The node:vfs module provides a virtual file system with a node:fs-like API.\nIt is useful for tests, fixtures, embedded assets, and other scenarios where you\nneed a self-contained file system without touching the actual file-system.
To access it:
\nimport vfs from 'node:vfs';\nconst vfs = require('node:vfs');\nThis module is only available under the node: scheme, and only when Node.js\nis started with the --experimental-vfs flag.
The VFS API is not a sandbox, permission system, or access-control mechanism.\nIt does not isolate untrusted code from the host file system or from other\nNode.js capabilities. Code that can access a VirtualFileSystem instance,\nmount it, select its provider, or pass paths to it is trusted application code.
Mounting a VFS only redirects supported node:fs calls whose resolved paths\nare under the mount point. It does not prevent code from using other paths or\nother Node.js APIs to access resources available to the process.\nRealFSProvider maps VFS paths under its configured root and rejects paths\nthat resolve outside that root, but that check is not a security boundary.\nZipProvider has no real file-system paths of its own to escape; its\nentries only ever exist within the archive's own namespace. Do not rely on VFS\nto run untrusted code; use operating-system-level isolation, such as separate\nusers, containers, or platform sandboxes, when a security boundary is\nrequired.
const vfs = require('node:vfs');\n\nconst myVfs = vfs.create();\nmyVfs.mkdirSync('/dir', { recursive: true });\nmyVfs.writeFileSync('/dir/hello.txt', 'Hello, VFS!');\n\nconsole.log(myVfs.readFileSync('/dir/hello.txt', 'utf8')); // 'Hello, VFS!'\nvfs.create() returns a VirtualFileSystem instance backed by a\nMemoryProvider by default. The instance exposes synchronous,\ncallback-based, and promise-based file system methods that mirror the\nshape of the node:fs API. All paths are POSIX-style and absolute\n(starting with /).
By default, the file tree is private to the VFS instance. To expose\nit through the global node:fs module, require(), and import,\ncall vfs.mount(); call vfs.unmount() (or rely on a\nusing declaration) to detach again.
Once a VirtualFileSystem is mounted, paths under the mount point\nparticipate in module resolution and loading. The CommonJS\nresolution algorithm used by require() and\nrequire.resolve() and the ES modules resolution algorithm\nused by import and import.meta.resolve() are unchanged;\ninstead, every file system operation those algorithms perform is\ndispatched on the path being probed: paths under a mount point are\nserved by the owning VFS, and all other paths are served by the real\nfile system. Files served from the VFS therefore behave as\nfirst-class modules.
Because mounted paths live in a reserved namespace that cannot exist\non disk, any given path is served either by exactly one VFS or by\nthe real file system, never both. There is no search order or\nfallback between the two: if a path under a mount point does not\nexist in the VFS, resolution fails with ENOENT without consulting\nthe disk, and a mounted layer never shadows a real directory.
For resolution purposes the mount point behaves as a file system\nroot: package.json scope lookups and loading from node_modules\nfolders stop at the mount point. For example, when\n${mountPoint}/foo/bar/main.cjs calls require('baz'), the lookup\ngoes through:
${mountPoint}/foo/bar/node_modules/baz${mountPoint}/foo/node_modules/baz${mountPoint}/node_modules/baz$NODE_PATH is set, the folders listed in $NODE_PATH$HOME/.node_modules/baz$HOME/.node_libraries/baz$PREFIX/lib/node/bazThe last four entries are the global folders, which are legacy\nCommonJS behavior and do not apply to import. Absolute specifiers\nmay cross the boundary in either direction: a module on the real\nfile system can require() a mounted path, and a virtual module can\nrequire() a real one.
const vfs = require('node:vfs');\n\nconst myVfs = vfs.create();\nmyVfs.mkdirSync('/lib');\nmyVfs.writeFileSync('/lib/greet.js', 'module.exports = () => \"hi\";');\nmyVfs.writeFileSync(\n '/lib/package.json', '{\"main\": \"./greet.js\"}');\nconst mountPoint = myVfs.mount();\n\nconst greet = require(`${mountPoint}/lib`);\nconsole.log(greet()); // 'hi'\n\nmyVfs.unmount();\nFor ECMAScript modules, use file: URLs when passing mounted paths\nto dynamic import(). vfs.mountPointURL provides the mount\npoint in that form; this keeps VFS imports portable on Windows,\nwhere mounted paths use Windows path syntax.
import vfs from 'node:vfs';\n\nconst myVfs = vfs.create();\nmyVfs.writeFileSync('/mod.mjs', 'export const value = 42;');\nmyVfs.mount();\n\nconst { value } = await import(`${myVfs.mountPointURL}/mod.mjs`);\nconsole.log(value); // 42\n\nmyVfs.unmount();\nCommonJS modules loaded from a mounted VFS are identified by their VFS paths\nthat start with the mount point. This is reflected in, for example, __filename and\n__dirname in the module, or the errors stack traces involving functions from\nthe VFS modules. ES modules in the VFS are similarly identified by the file: URL of\ntheir VFS paths and this is reflected in e.g. import.meta.url.
Like modules loaded from the real file system, modules loaded from the VFS are\ncached on the first load. When require() or import() is used to load an absolute\npath or URL that falls under the mounted VFS multiple times, the module is only loaded\nonce and subsequent calls return the same instance.
Calling vfs.unmount() invalidates the modules that were loaded\nfrom the mount point: a subsequent require() or import of a path\nunder a re-created mount re-reads the file from the newly mounted\nVFS rather than returning a stale module. Modules loaded from other\nVFS instances or from the real file system are unaffected.
Mounting and unmounting do not stop any module execution that is\nalready started, or invalidate any objects materialized from VFS\nmodules that are already executed. As with modules in the real file\nsystem, the callers are responsible for avoiding removal or\ninvalidation of modules in the virtual file system while they are\nbeing loaded.
", "displayName": "Module loader integration" }, { "textRaw": "Implementation details", "name": "implementation_details", "type": "module", "modules": [ { "textRaw": "`Stats` objects", "name": "`stats`_objects", "type": "module", "desc": "VFS Stats objects are real instances of fs.Stats (or\nfs.BigIntStats when { bigint: true } is requested). Their\nfields use synthetic but stable values:
dev is 4085 (the VFS device id).ino is monotonically increasing per process.blksize is 4096.blocks is Math.ceil(size / 512).Convenience factory equivalent to new VirtualFileSystem(provider, options).
const vfs = require('node:vfs');\n\n// Default in-memory provider\nconst memoryVfs = vfs.create();\n\n// Explicit provider\nconst realVfs = vfs.create(new vfs.RealFSProvider('/tmp/vfs-root'));\nA VirtualFileSystem wraps a VirtualProvider and exposes a\nnode:fs-like API. Each instance maintains its own file tree.
Mounts the virtual file system and returns the resulting mount point.\nAfter mounting, files in the VFS can be accessed through the\nnode:fs module and resolved through require() and import\nusing paths under the returned mount point.
Mount points always live inside a reserved namespace that cannot have child file system entries,\nso virtual paths never conflate with (or shadow) real paths. The virtual path scheme is subject to\nchange and users should not manually construct them based on assumptions. Instead, obtain\nthem from what vfs.mount() returns or vfs.mountPoint.
const vfs = require('node:vfs');\nconst fs = require('node:fs');\n\nconst myVfs = vfs.create();\nmyVfs.writeFileSync('/data.txt', 'Hello');\nconst mountPoint = myVfs.mount();\n// e.g. '/dev/null/vfs/0'\n\nfs.readFileSync(`${mountPoint}/data.txt`, 'utf8'); // 'Hello'\nEach VirtualFileSystem instance may be mounted at most once at a\ntime. Attempting to mount an already-mounted instance throws\nERR_INVALID_STATE. Because each instance mounts inside its own\nper-layer namespace, mounts from different instances can never\noverlap.
The VFS supports the Explicit Resource Management proposal. Use\na using declaration to unmount automatically when leaving scope:
const vfs = require('node:vfs');\nconst fs = require('node:fs');\n\nlet mountPoint;\n{\n using myVfs = vfs.create();\n myVfs.writeFileSync('/data.txt', 'Hello');\n mountPoint = myVfs.mount();\n\n fs.readFileSync(`${mountPoint}/data.txt`, 'utf8'); // 'Hello'\n} // VFS is automatically unmounted here\n\nfs.existsSync(`${mountPoint}/data.txt`); // false\nUnmounts the virtual file system. After unmounting, virtual files\nare no longer reachable through node:fs, require(), or import.\nThe same instance may be mounted again by calling mount().
This method is idempotent: calling unmount() on a VFS that is not\ncurrently mounted has no effect.
true while the VFS is mounted; false otherwise.
The current mount point as an absolute string (the value returned by\nthe last vfs.mount() call), or null when the VFS is not\nmounted.
The current mount point as a file: URL string (the vfs.mountPoint\npath converted with url.pathToFileURL()), or null when the VFS\nis not mounted.
This is a convenience for addressing mounted files with URL-based\nAPIs such as dynamic import():
import vfs from 'node:vfs';\n\nconst myVfs = vfs.create();\nmyVfs.writeFileSync('/mod.mjs', 'export const value = 42;');\nmyVfs.mount();\n\nconst { value } = await import(`${myVfs.mountPointURL}/mod.mjs`);\nconsole.log(value); // 42\n\nmyVfs.unmount();\nThe provider backing this VFS instance.
" }, { "textRaw": "{boolean}", "name": "readonly", "type": "boolean", "meta": { "added": [ "v26.4.0" ], "changes": [] }, "desc": "true when the underlying provider is read-only.
VirtualFileSystem implements the following methods, with the same\nsignatures as their node:fs counterparts:
existsSync(path)statSync(path[, options])lstatSync(path[, options])readFileSync(path[, options])writeFileSync(path, data[, options])appendFileSync(path, data[, options])readdirSync(path[, options])mkdirSync(path[, options])rmdirSync(path)unlinkSync(path)renameSync(oldPath, newPath)copyFileSync(src, dest[, mode])realpathSync(path[, options])readlinkSync(path[, options])symlinkSync(target, path[, type])accessSync(path[, mode])rmSync(path[, options])truncateSync(path[, len])ftruncateSync(fd[, len])linkSync(existingPath, newPath)chmodSync(path, mode)chownSync(path, uid, gid)lchownSync(path, uid, gid)utimesSync(path, atime, mtime)lutimesSync(path, atime, mtime)mkdtempSync(prefix)opendirSync(path[, options])openAsBlob(path[, options])openSync, closeSync, readSync, writeSync,\nfstatSynccreateReadStream, createWriteStreamwatch, watchFile, unwatchFilereadFile, writeFile, stat, lstat, readdir, realpath, readlink,\naccess, open, close, read, write, rm, fstat, truncate,\nftruncate, link, mkdtemp, opendir. Each takes a Node.js-style\ncallback (err, ...result) => {}.
vfs.promises exposes the promise-based variants:
const vfs = require('node:vfs');\n\nasync function example() {\n const myVfs = vfs.create();\n await myVfs.promises.writeFile('/file.txt', 'hello');\n const data = await myVfs.promises.readFile('/file.txt', 'utf8');\n return data;\n}\nexample();\nThe promise namespace mirrors fs.promises and includes readFile,\nwriteFile, appendFile, stat, lstat, readdir, mkdir, rmdir,\nunlink, rename, copyFile, realpath, readlink, symlink,\naccess, rm, truncate, link, mkdtemp, chmod, chown, lchown,\nutimes, lutimes, open, lchmod, and watch.
The base class for all VFS providers. Subclasses implement the essential\nprimitives (such as open, stat, readdir, mkdir, rmdir, unlink,\nrename, etc.) and inherit default implementations of the derived\nmethods (such as readFile, writeFile, exists, copyFile, access, etc.).
provider.readonly <boolean> Default: false.provider.supportsSymlinks <boolean> Default: false.provider.supportsWatch <boolean> Default: false.const { VirtualProvider } = require('node:vfs');\n\nclass StaticProvider extends VirtualProvider {\n get readonly() { return true; }\n\n statSync(path) { /* ... */ }\n openSync(path, flags) { /* ... */ }\n readdirSync(path, options) { /* ... */ }\n // ...\n}\nThe base class throws ERR_METHOD_NOT_IMPLEMENTED for any primitive\nthat has not been overridden, and rejects writes from a readonly\nprovider with EROFS.
The default in-memory provider. Stores files, directories, and symbolic\nlinks in a Map-backed tree, supports symlinks (supportsSymlinks === true), and supports watching (supportsWatch === true).
Locks the provider into read-only mode. Subsequent writes through any\nVirtualFileSystem using this provider throw EROFS. There is no\nway to revert the provider to writable.
const vfs = require('node:vfs');\n\nconst provider = new vfs.MemoryProvider();\nconst myVfs = vfs.create(provider);\nmyVfs.writeFileSync('/seed.txt', 'initial');\n\nprovider.setReadOnly();\n\nmyVfs.writeFileSync('/x.txt', 'fail'); // throws EROFS\nA provider that wraps a directory (i.e. one on the actual file system) and\nexposes its contents through the VFS API. All VFS paths are resolved relative to\nthe root and verified to stay inside it; symbolic links resolving outside the\nroot are rejected. This path mapping is not a sandbox or access-control\nmechanism.
", "signatures": [ { "textRaw": "`new RealFSProvider(rootPath)`", "name": "RealFSProvider", "type": "ctor", "meta": { "added": [ "v26.4.0" ], "changes": [] }, "params": [ { "textRaw": "`rootPath` {string} The absolute file-system path to use as the root. Must be a non-empty string.", "name": "rootPath", "type": "string", "desc": "The absolute file-system path to use as the root. Must be a non-empty string." } ], "desc": "const vfs = require('node:vfs');\n\nconst realVfs = vfs.create(new vfs.RealFSProvider('/tmp/vfs-root'));\nrealVfs.writeFileSync('/file.txt', 'hello'); // writes /tmp/vfs-root/file.txt\nThe resolved absolute path used as the root.
" } ] }, { "textRaw": "Class: `ZipProvider`", "name": "ZipProvider", "type": "class", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "A provider that exposes the entries of a ZIP archive - either a\nzlib.ZipBuffer (in memory) or a zlib.ZipFile (on disk) - through\nthe VFS API. provider.readonly reflects the archive's own\nzipFile.writable flag: a ZipBuffer is always writable, and a\nZipFile is writable only when opened with { writable: true }.
Directories are recognized both explicitly (an entry whose name ends in /)\nand implicitly (any entry name starting with \"<dir>/\"). readdir() does\nnot support { recursive: true }. Because a ZIP member cannot be edited or\nread in place - only fully written or fully decompressed - a file opened for\nwriting only commits its content (as a new archive entry) when the handle is\nclosed.
Every method has a synchronous counterpart (openSync(), statSync(),\nreaddirSync(), and so on), backed by the equally complete synchronous\nsurface zlib.ZipBuffer/zlib.ZipFile expose. As with those, the\nsynchronous methods here block the Node.js event loop and further JavaScript\nexecution until the operation - including any deflate/inflate pass -\ncompletes.
const vfs = require('node:vfs');\nconst zlib = require('node:zlib');\nconst { readFileSync } = require('node:fs');\n\nasync function main() {\n const zip = new zlib.ZipBuffer(readFileSync('archive.zip'));\n const archiveVfs = vfs.create(new vfs.ZipProvider(zip));\n\n console.log(await archiveVfs.promises.readdir('/'));\n await archiveVfs.promises.writeFile('/new.txt', 'hello');\n}\nmain();\n