{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.0.json","id":"vfs","path":"/vfs","type":"module","module":"vfs","title":"Virtual File System","introducedIn":"v26.4.0","sourceLink":{"path":"lib/vfs.js","url":"https://github.com/nodejs/node/blob/HEAD/lib/vfs.js"},"stability":{"index":"1","description":"Experimental"},"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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.\n\nTo access it:\n\n```mjs\nimport vfs from 'node:vfs';\n```\n\n```cjs\nconst vfs = require('node:vfs');\n```\n\nThis module is only available under the `node:` scheme, and only when Node.js\nis started with the `--experimental-vfs` flag.","summary":"The `node:vfs` module provides a virtual file system with a `node:fs`-like API. It is useful for tests, fixtures, embedded assets, and other scenarios where you need a self-contained file system without touching the actual file-system.","examples":[{"language":"mjs","displayName":null,"code":"import vfs from 'node:vfs';"},{"language":"cjs","displayName":null,"code":"const vfs = require('node:vfs');"}],"children":[{"kind":"section","id":"security","name":"Security","title":"Security","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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`](#class-virtualfilesystem) instance,\nmount it, select its provider, or pass paths to it is trusted application code.\n\nMounting a VFS only redirects supported [`node:fs`](fs.html) 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.\n[`RealFSProvider`](#class-realfsprovider) maps VFS paths under its configured root and rejects paths\nthat resolve outside that root, but that check is not a security boundary. Do\nnot rely on VFS to run untrusted code; use operating-system-level isolation,\nsuch as separate users, containers, or platform sandboxes, when a security\nboundary is required.","summary":"The VFS API is not a sandbox, permission system, or access-control mechanism. It does not isolate untrusted code from the host file system or from other Node.js capabilities. Code that can access a `VirtualFileSystem` instance, mount it, select its provider, or pass paths to it is trusted application code.","examples":[],"children":[]},{"kind":"section","id":"basic-usage","name":"Basic usage","title":"Basic usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```cjs\nconst 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!'\n```\n\n`vfs.create()` returns a [`VirtualFileSystem`](#class-virtualfilesystem) instance backed by a\n[`MemoryProvider`](#class-memoryprovider) by default. The instance exposes synchronous,\ncallback-based, and promise-based file system methods that mirror the\nshape of the [`node:fs`](fs.html) API. All paths are POSIX-style and absolute\n(starting with `/`).","summary":"`vfs.create()` returns a `VirtualFileSystem` instance backed by a `MemoryProvider` by default. The instance exposes synchronous, callback-based, and promise-based file system methods that mirror the shape of the `node:fs` API. All paths are POSIX-style and absolute (starting with `/`).","examples":[{"language":"cjs","displayName":null,"code":"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!'"}],"children":[]},{"kind":"method","id":"vfscreateprovider-options","name":"create","title":"`vfs.create([provider][, options])`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"provider","type":{"text":"VirtualProvider","links":[{"name":"VirtualProvider","href":"vfs.html#class-virtualprovider","start":0,"end":15}]},"description":"The provider to use.","default":"new MemoryProvider()","optional":true,"rest":false,"properties":[]},{"name":"options","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"","default":null,"optional":true,"rest":false,"properties":[{"name":"emitExperimentalWarning","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"Whether to emit the experimental\nwarning when the instance is created.","default":"true","optional":true,"rest":false,"properties":[]}]}],"returns":{"type":{"text":"VirtualFileSystem","links":[{"name":"VirtualFileSystem","href":"vfs.html#class-virtualfilesystem","start":0,"end":17}]},"description":""}},"description":"Convenience factory equivalent to `new VirtualFileSystem(provider, options)`.\n\n```cjs\nconst 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'));\n```","summary":"Convenience factory equivalent to `new VirtualFileSystem(provider, options)`.","examples":[{"language":"cjs","displayName":null,"code":"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'));"}],"children":[]},{"kind":"class","id":"class-virtualfilesystem","name":"VirtualFileSystem","title":"Class: `VirtualFileSystem`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"A `VirtualFileSystem` wraps a [`VirtualProvider`](#class-virtualprovider) and exposes a\n`node:fs`-like API. Each instance maintains its own file tree.","summary":"A `VirtualFileSystem` wraps a `VirtualProvider` and exposes a `node:fs`-like API. Each instance maintains its own file tree.","examples":[],"children":[{"kind":"constructor","id":"new-virtualfilesystemprovider-options","name":"VirtualFileSystem","title":"`new VirtualFileSystem([provider][, options])`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"provider","type":{"text":"VirtualProvider","links":[{"name":"VirtualProvider","href":"vfs.html#class-virtualprovider","start":0,"end":15}]},"description":"The provider to use.","default":"new MemoryProvider()","optional":true,"rest":false,"properties":[]},{"name":"options","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"","default":null,"optional":true,"rest":false,"properties":[{"name":"emitExperimentalWarning","type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"description":"Whether to emit the experimental\nwarning.","default":"true","optional":true,"rest":false,"properties":[]}]}],"returns":null},"description":"","summary":"","examples":[],"children":[]},{"kind":"property","id":"vfsprovider","name":"provider","title":"`vfs.provider`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"VirtualProvider","links":[{"name":"VirtualProvider","href":"vfs.html#class-virtualprovider","start":0,"end":15}]},"default":null,"description":"The provider backing this VFS instance.","summary":"The provider backing this VFS instance.","examples":[],"children":[]},{"kind":"property","id":"vfsreadonly","name":"readonly","title":"`vfs.readonly`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"boolean","links":[{"name":"boolean","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type","start":0,"end":7}]},"default":null,"description":"`true` when the underlying provider is read-only.","summary":"`true` when the underlying provider is read-only.","examples":[],"children":[]},{"kind":"section","id":"apis","name":"APIs","title":"APIs","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`VirtualFileSystem` implements the following methods, with the same\nsignatures as their [`node:fs`](fs.html) counterparts:","summary":"`VirtualFileSystem` implements the following methods, with the same signatures as their `node:fs` counterparts:","examples":[],"children":[{"kind":"section","id":"synchronous-api","name":"Synchronous API","title":"Synchronous API","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* `existsSync(path)`\n* `statSync(path[, options])`\n* `lstatSync(path[, options])`\n* `readFileSync(path[, options])`\n* `writeFileSync(path, data[, options])`\n* `appendFileSync(path, data[, options])`\n* `readdirSync(path[, options])`\n* `mkdirSync(path[, options])`\n* `rmdirSync(path)`\n* `unlinkSync(path)`\n* `renameSync(oldPath, newPath)`\n* `copyFileSync(src, dest[, mode])`\n* `realpathSync(path[, options])`\n* `readlinkSync(path[, options])`\n* `symlinkSync(target, path[, type])`\n* `accessSync(path[, mode])`\n* `rmSync(path[, options])`\n* `truncateSync(path[, len])`\n* `ftruncateSync(fd[, len])`\n* `linkSync(existingPath, newPath)`\n* `chmodSync(path, mode)`\n* `chownSync(path, uid, gid)`\n* `lchownSync(path, uid, gid)`\n* `utimesSync(path, atime, mtime)`\n* `lutimesSync(path, atime, mtime)`\n* `mkdtempSync(prefix)`\n* `opendirSync(path[, options])`\n* `openAsBlob(path[, options])`\n* File-descriptor ops: `openSync`, `closeSync`, `readSync`, `writeSync`,\n  `fstatSync`\n* Streams: `createReadStream`, `createWriteStream`\n* Watchers: `watch`, `watchFile`, `unwatchFile`","summary":"","examples":[],"children":[]},{"kind":"section","id":"callback-api","name":"Callback API","title":"Callback API","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`readFile`, `writeFile`, `stat`, `lstat`, `readdir`, `realpath`, `readlink`,\n`access`, `open`, `close`, `read`, `write`, `rm`, `fstat`, `truncate`,\n`ftruncate`, `link`, `mkdtemp`, `opendir`. Each takes a Node.js-style\ncallback `(err, ...result) => {}`.","summary":"`readFile`, `writeFile`, `stat`, `lstat`, `readdir`, `realpath`, `readlink`, `access`, `open`, `close`, `read`, `write`, `rm`, `fstat`, `truncate`, `ftruncate`, `link`, `mkdtemp`, `opendir`. Each takes a Node.js-style callback `(err, ...result) => {}`.","examples":[],"children":[]},{"kind":"section","id":"promise-api","name":"Promise API","title":"Promise API","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`vfs.promises` exposes the promise-based variants:\n\n```cjs\nconst 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();\n```\n\nThe promise namespace mirrors `fs.promises` and includes `readFile`,\n`writeFile`, `appendFile`, `stat`, `lstat`, `readdir`, `mkdir`, `rmdir`,\n`unlink`, `rename`, `copyFile`, `realpath`, `readlink`, `symlink`,\n`access`, `rm`, `truncate`, `link`, `mkdtemp`, `chmod`, `chown`, `lchown`,\n`utimes`, `lutimes`, `open`, `lchmod`, and `watch`.","summary":"`vfs.promises` exposes the promise-based variants:","examples":[{"language":"cjs","displayName":null,"code":"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();"}],"children":[]}]}]},{"kind":"class","id":"class-virtualprovider","name":"VirtualProvider","title":"Class: `VirtualProvider`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"The base class for all VFS providers. Subclasses implement the essential\nprimitives (such as `open`, `stat`, `readdir`, `mkdir`, `rmdir`, `unlink`,\n`rename`, etc.) and inherit default implementations of the derived\nmethods (such as `readFile`, `writeFile`, `exists`, `copyFile`, `access`, etc.).","summary":"The base class for all VFS providers. Subclasses implement the essential primitives (such as `open`, `stat`, `readdir`, `mkdir`, `rmdir`, `unlink`, `rename`, etc.) and inherit default implementations of the derived methods (such as `readFile`, `writeFile`, `exists`, `copyFile`, `access`, etc.).","examples":[],"children":[{"kind":"section","id":"capability-flags","name":"Capability flags","title":"Capability flags","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* `provider.readonly` {boolean} **Default:** `false`.\n* `provider.supportsSymlinks` {boolean} **Default:** `false`.\n* `provider.supportsWatch` {boolean} **Default:** `false`.","summary":"","examples":[],"children":[]},{"kind":"section","id":"creating-custom-providers","name":"Creating custom providers","title":"Creating custom providers","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```cjs\nconst { 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}\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`.","summary":"The base class throws `ERR_METHOD_NOT_IMPLEMENTED` for any primitive that has not been overridden, and rejects writes from a `readonly` provider with `EROFS`.","examples":[{"language":"cjs","displayName":null,"code":"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}"}],"children":[]}]},{"kind":"class","id":"class-memoryprovider","name":"MemoryProvider","title":"Class: `MemoryProvider`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"The default in-memory provider. Stores files, directories, and symbolic\nlinks in a `Map`-backed tree, supports symlinks (`supportsSymlinks ===\ntrue`), and supports watching (`supportsWatch === true`).","summary":"The default in-memory provider. Stores files, directories, and symbolic links in a `Map`-backed tree, supports symlinks (`supportsSymlinks ===true`), and supports watching (`supportsWatch === true`).","examples":[],"children":[{"kind":"method","id":"memoryprovidersetreadonly","name":"setReadOnly","title":"`memoryProvider.setReadOnly()`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":null},"description":"Locks the provider into read-only mode. Subsequent writes through any\n[`VirtualFileSystem`](#class-virtualfilesystem) using this provider throw `EROFS`. There is no\nway to revert the provider to writable.\n\n```cjs\nconst 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\n```","summary":"Locks the provider into read-only mode. Subsequent writes through any `VirtualFileSystem` using this provider throw `EROFS`. There is no way to revert the provider to writable.","examples":[{"language":"cjs","displayName":null,"code":"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"}],"children":[]}]},{"kind":"class","id":"class-realfsprovider","name":"RealFSProvider","title":"Class: `RealFSProvider`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"A 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.","summary":"A provider that wraps a directory (i.e. one on the actual file system) and exposes its contents through the VFS API. All VFS paths are resolved relative to the root and verified to stay inside it; symbolic links resolving outside the root are rejected. This path mapping is not a sandbox or access-control mechanism.","examples":[],"children":[{"kind":"constructor","id":"new-realfsproviderrootpath","name":"RealFSProvider","title":"`new RealFSProvider(rootPath)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"rootPath","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"The absolute file-system path to use as the root.\nMust be a non-empty string.","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"```cjs\nconst 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\n```","summary":"","examples":[{"language":"cjs","displayName":null,"code":"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"}],"children":[]},{"kind":"property","id":"realfsproviderrootpath","name":"rootPath","title":"`realFSProvider.rootPath`","scope":"module","overloadOf":null,"stability":null,"added":["v26.4.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"default":null,"description":"The resolved absolute path used as the root.","summary":"The resolved absolute path used as the root.","examples":[],"children":[]}]},{"kind":"section","id":"implementation-details","name":"Implementation details","title":"Implementation details","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"","summary":"","examples":[],"children":[{"kind":"section","id":"stats-objects","name":"Stats objects","title":"`Stats` objects","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"VFS `Stats` objects are real instances of [`fs.Stats`](fs.html#class-fsstats) (or\n[`fs.BigIntStats`](fs.html#class-fsstats) when `{ bigint: true }` is requested). Their\nfields use synthetic but stable values:\n\n* `dev` is `4085` (the VFS device id).\n* `ino` is monotonically increasing per process.\n* `blksize` is `4096`.\n* `blocks` is `Math.ceil(size / 512)`.\n* Times default to the moment the entry was created/last modified.","summary":"VFS `Stats` objects are real instances of `fs.Stats` (or `fs.BigIntStats` when `{ bigint: true }` is requested). Their fields use synthetic but stable values:","examples":[],"children":[]}]}]}