rules/api.md
GitHubnode:vfs API reference
Source: doc/api/vfs.md at nodejs/node ab476eccd03. Everything here is
Stability 1 (Experimental). Items marked verified were run on v26.13.0
(with --experimental-vfs) and v28.0.0-pre. The rest comes from the docs.
Module
| Export | Added | Notes |
|---|---|---|
vfs.create([provider][, options]) |
v26.4.0 | Same as new VirtualFileSystem(provider, options). Default provider is new MemoryProvider(). options.emitExperimentalWarning (default true). |
vfs.registerProvider({ name, canHandle(path, stats), create(path, stats) }) |
v26.10.0 | Only affects --vfs-load. Register from a --require/--import preload. Newest registration is asked first, before the built-ins. Providers are offered directories as well as files. |
vfs.vfsBase() |
v26.11.0 | Returns path.join(os.devNull, 'vfs'), which is /dev/null/vfs on POSIX (verified). |
VirtualFileSystem, VirtualProvider, MemoryProvider |
v26.4.0 | |
RealFSProvider |
v26.4.0 | |
ZipProvider |
v26.9.0 | |
ComposableProvider |
v26.12.0 |
Importing node:vfs emits one ExperimentalWarning ("VirtualFileSystem is an
experimental feature"). Verified: it is emitted once per process.
VirtualFileSystem instance
| Member | Added | Notes |
|---|---|---|
mount() |
v26.9.0 | Returns the mount point. Throws ERR_INVALID_STATE if this instance is already mounted (verified). |
unmount() |
v26.9.0 | Idempotent. Invalidates modules loaded from the mount. |
mounted |
v26.9.0 | boolean |
mountPoint / mountPointURL |
v26.9.0 | string | null. The URL form is for import(). |
provider, readonly |
v26.4.0 | |
[Symbol.dispose] |
— | using unmounts (verified). |
promises |
— | The promise API. |
The sync methods have the same signatures as their node:fs
counterparts: existsSync statSync lstatSync readFileSync writeFileSync appendFileSync readdirSync mkdirSync rmdirSync unlinkSync renameSync copyFileSync realpathSync readlinkSync symlinkSync accessSync rmSync truncateSync ftruncateSync linkSync chmodSync chownSync lchownSync utimesSync lutimesSync mkdtempSync mkstempSync opendirSync openAsBlob openSync closeSync readSync writeSync fstatSync createReadStream createWriteStream watch watchFile unwatchFile.
The callback methods are readFile writeFile stat lstat readdir realpath readlink access open close read write rm fstat truncate ftruncate link mkdtemp mkstemp opendir.
The promise methods (v.promises) are readFile writeFile appendFile stat lstat readdir mkdir rmdir unlink rename copyFile realpath readlink symlink access rm truncate link mkdtemp mkstemp chmod chown lchown utimes lutimes open lchmod watch.
Paths are POSIX-style and absolute. Observed on both builds: while the
instance is mounted, its own methods resolve paths under the mount point.
v.readFileSync('/a') throws ENOENT, while v.readFileSync(${mp}/a)
works. After unmount(), /a works again. Seed fixtures before you mount,
or write with mount-prefixed paths. This is not documented; see meta.json.
Stats objects are real fs.Stats instances (verified). dev is 4085,
blksize is 4096, and ino increases monotonically.
Through node:fs once mounted (verified on v26.13.0 and v28.0.0-pre)
These work: readFile/writeFile/appendFile (all three API styles),
readdir (withFileTypes, recursive), opendir, stat, access,
realpath, rename within the mount, mkdtemp, fs.promises.open
(FileHandle), createReadStream/createWriteStream, openAsBlob, and
fs.watch.
These do not work:
fs.glob/fs.globSyncreturns[].fs.cp/cpSyncfails (ENOTDIRon/dev/null/...).renameorcopyFilebetween the mount and the real fs fails withEXDEV.- Child processes cannot see the mount, because it does not exist in the OS.
The mount point itself cannot be removed or renamed (EBUSY), and a recursive
fs.rm of it first empties it. Under the reserved root, creating or removing
entries fails with EROFS (verified). The root lists one directory per
mounted instance, and does not exist when nothing is mounted (verified).
Mount names are assigned at runtime. --vfs-load and SEA mounts used /0,
and vfs.mount() used /1 on main and v26.13.0. Never construct mount paths
yourself.
Module loader
- The CJS and ESM resolution algorithms are unchanged. Every fs probe they make
goes to the VFS when the path is under a mount, and to disk otherwise. There
is no fallback: a missing path under a mount is
ENOENT. - The mount acts as a filesystem root, so
node_modulesandpackage.jsonscope lookups stop at it. After that, CJS still consultsNODE_PATHand the legacy global folders. - Absolute specifiers may cross in either direction.
__filenameandimport.meta.urlshow the VFS path, for examplefile:///dev/null/vfs/1/mod.mjs(verified). On Windows, usemountPointURLforimport().- Modules are cached like disk modules.
unmount()invalidates the cache for that mount. - The docs say
.nodeaddons andffi.dlopen()libraries inside a mount load from a private temporary copy. Verified forffi.dlopen()oflibm.so.6copied into a mount, on main and v26.13.0. Addons are not verified.
Providers
MemoryProvider (v26.4.0)
A Map-backed tree with supportsSymlinks and supportsWatch.
provider.setReadOnly() is one-way: after it, writes throw EROFS.
RealFSProvider(rootPath) (v26.4.0)
Wraps a real directory, and rootPath is exposed. .. cannot climb out of
the root (verified: ENOENT).
Observed, contrary to the docs: a symlink inside the root that points
outside it is followed by readFileSync, both directly and through the mount.
Only realpathSync refuses it, with EACCES. This is not a security boundary.
ZipProvider(source) (v26.9.0)
source is a zlib.ZipBuffer (in memory, always writable) or a
zlib.ZipFile (on disk, writable only when opened with { writable: true }).
readonly mirrors the source (verified: a ZipFile opened with openSync
gives readonly === true and writes fail with EROFS). Directories can be
explicit (a dir/ entry) or implicit (a path prefix). A file opened for
writing is committed as a new entry when its handle closes. Writes go to the
ZipBuffer index, not to the original bytes. Call zipBuffer.toBuffer() to
serialize.
To build a zip with node:zlib (v26.8.0+), use
createZipArchiveSync([ZipEntry.createSync(name, data), …]), which yields
Buffer chunks, or zipFiles([[src, name], …]), which returns a Readable.
new ZipBuffer(Buffer.alloc(0)) throws ERR_ZIP_INVALID_ARCHIVE.
ComposableProvider(providers[]) (v26.12.0)
The first provider is the writable top layer, and reads search layers in order. Directories are merged. A write to a lower file copies it up first. Unlinking hides lower copies without deleting them (verified: disk is untouched).
Limitations from the docs:
- Symlinks resolve only within their own layer.
- Traversal through a symlinked directory is not supported.
- Renaming over a directory that exists only in a lower layer is not supported.
watchwatches only the selected layer.- Copy-up is synchronous, even from the async API.
providersreturns a copy.
Custom providers
Subclass VirtualProvider and implement the primitives (openSync,
statSync, readdirSync, mkdirSync, rmdirSync, unlinkSync,
renameSync, …). The derived methods are inherited. Capability getters:
readonly, supportsSymlinks, and supportsWatch (all default false). An
unimplemented primitive throws ERR_METHOD_NOT_IMPLEMENTED, and writes on a
readonly provider throw EROFS. Not verified here: the full set of
primitives a provider needs is only sketched in the docs.