{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.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.\n[`ZipProvider`](#class-zipprovider) 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.","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 `/`).\n\nBy 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()`](#vfsmount); call [`vfs.unmount()`](#vfsunmount) (or rely on a\n`using` declaration) to detach again.","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":"method","id":"vfsregisterproviderentry","name":"registerProvider","title":"`vfs.registerProvider(entry)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.10.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"entry","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":false,"rest":false,"properties":[{"name":"name","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":"A short identifier, used in diagnostics.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"canHandle","type":{"text":"Function","links":[{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":0,"end":8}]},"description":"Called with the resolved path and its\n[`fs.Stats`](fs.html#class-fsstats). Returns `true` if this provider should back the source.","default":null,"optional":false,"rest":false,"properties":[]},{"name":"create","type":{"text":"Function","links":[{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":0,"end":8}]},"description":"Called with the resolved path and its [`fs.Stats`](fs.html#class-fsstats).\nReturns the {VirtualProvider} backing the source.","default":null,"optional":false,"rest":false,"properties":[]}]}],"returns":null},"description":"Registers a provider that [`--vfs-mount`](cli.html#--vfs-mountsource) can select for a source it\nrecognizes, so a file format Node.js has no built-in provider for can still be\nmounted.\n\nA source is claimed by the first provider whose `canHandle()` returns `true`.\nRegistered providers are consulted before the built-in ones, newest\nregistration first, and are offered directories as well as files, so a\nregistered provider can back, wrap, or vet any source. If none claims the\nsource, the built-in providers handle it: a directory with\n[`RealFSProvider`](#class-realfsprovider), and a file whose bytes are a ZIP archive with\n[`ZipProvider`](#class-zipprovider).\n\nProviders must be registered before the mounts are created. Register from a\nmodule preloaded with [`--require`](cli.html#-r---require-module) or [`--import`](cli.html#--importmodule):\n\n```cjs\n// provider.js, preloaded with --require\nconst fs = require('node:fs');\nconst vfs = require('node:vfs');\n\nconst MAGIC = Buffer.from('CUSTOMFMT');\n\nvfs.registerProvider({\n  name: 'customfmt',\n  canHandle(path, stats) {\n    if (!stats.isFile()) return false;\n    const head = Buffer.alloc(MAGIC.length);\n    const fd = fs.openSync(path, 'r');\n    try {\n      fs.readSync(fd, head, 0, MAGIC.length, 0);\n    } finally {\n      fs.closeSync(fd);\n    }\n    return head.equals(MAGIC);\n  },\n  create(path) {\n    return new MyCustomProvider(path);\n  },\n});\n```\n\n```console\n$ node --experimental-vfs --require ./provider.js \\\n       --vfs-load archive.customfmt\n```","summary":"Registers a provider that `--vfs-mount` can select for a source it recognizes, so a file format Node.js has no built-in provider for can still be mounted.","examples":[{"language":"cjs","displayName":null,"code":"// provider.js, preloaded with --require\nconst fs = require('node:fs');\nconst vfs = require('node:vfs');\n\nconst MAGIC = Buffer.from('CUSTOMFMT');\n\nvfs.registerProvider({\n  name: 'customfmt',\n  canHandle(path, stats) {\n    if (!stats.isFile()) return false;\n    const head = Buffer.alloc(MAGIC.length);\n    const fd = fs.openSync(path, 'r');\n    try {\n      fs.readSync(fd, head, 0, MAGIC.length, 0);\n    } finally {\n      fs.closeSync(fd);\n    }\n    return head.equals(MAGIC);\n  },\n  create(path) {\n    return new MyCustomProvider(path);\n  },\n});"},{"language":"console","displayName":null,"code":"$ node --experimental-vfs --require ./provider.js \\\n       --vfs-load archive.customfmt"}],"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":"method","id":"vfsmount","name":"mount","title":"`vfs.mount()`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":{"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 mount point."}},"description":"Mounts the virtual file system and returns the resulting mount point.\nAfter mounting, files in the VFS can be accessed through the\n`node:fs` module and resolved through `require()` and `import`\nusing paths under the returned mount point.\n\nMount 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`.\n\n```cjs\nconst 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'\n```\n\nEach `VirtualFileSystem` instance may be mounted at most once at a\ntime. Attempting to mount an already-mounted instance throws\n`ERR_INVALID_STATE`. Because each instance mounts inside its own\nper-layer namespace, mounts from different instances can never\noverlap.\n\nThe VFS supports the [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management) proposal. Use\na `using` declaration to unmount automatically when leaving scope:\n\n```cjs\nconst 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\n```","summary":"Mounts the virtual file system and returns the resulting mount point. After mounting, files in the VFS can be accessed through the `node:fs` module and resolved through `require()` and `import` using paths under the returned mount point.","examples":[{"language":"cjs","displayName":null,"code":"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'"},{"language":"cjs","displayName":null,"code":"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"}],"children":[]},{"kind":"method","id":"vfsunmount","name":"unmount","title":"`vfs.unmount()`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":null},"description":"Unmounts 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()`.\n\nThis method is idempotent: calling `unmount()` on a VFS that is not\ncurrently mounted has no effect.","summary":"Unmounts the virtual file system. After unmounting, virtual files are no longer reachable through `node:fs`, `require()`, or `import`. The same instance may be mounted again by calling `mount()`.","examples":[],"children":[]},{"kind":"property","id":"vfsmounted","name":"mounted","title":"`vfs.mounted`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.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` while the VFS is mounted; `false` otherwise.","summary":"`true` while the VFS is mounted; `false` otherwise.","examples":[],"children":[]},{"kind":"property","id":"vfsmountpoint","name":"mountPoint","title":"`vfs.mountPoint`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string | null","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"null","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#null_type","start":9,"end":13}]},"default":null,"description":"The current mount point as an absolute string (the value returned by\nthe last [`vfs.mount()`](#vfsmount) call), or `null` when the VFS is not\nmounted.","summary":"The current mount point as an absolute string (the value returned by the last `vfs.mount()` call), or `null` when the VFS is not mounted.","examples":[],"children":[]},{"kind":"property","id":"vfsmountpointurl","name":"mountPointURL","title":"`vfs.mountPointURL`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"type":{"text":"string | null","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6},{"name":"null","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#null_type","start":9,"end":13}]},"default":null,"description":"The current mount point as a `file:` URL string (the [`vfs.mountPoint`](#vfsmountpoint)\npath converted with [`url.pathToFileURL()`](url.html#urlpathtofileurlpath-options)), or `null` when the VFS\nis not mounted.\n\nThis is a convenience for addressing mounted files with URL-based\nAPIs such as dynamic `import()`:\n\n```mjs\nimport 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();\n```","summary":"The current mount point as a `file:` URL string (the `vfs.mountPoint` path converted with `url.pathToFileURL()`), or `null` when the VFS is not mounted.","examples":[{"language":"mjs","displayName":null,"code":"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();"}],"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":"section","id":"module-loader-integration","name":"Module loader integration","title":"Module loader integration","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Once a `VirtualFileSystem` is mounted, paths under the mount point\nparticipate in module resolution and loading. The [CommonJS\nresolution algorithm](modules.html#all-together) used by [`require()`](modules.html#requireid) and\n[`require.resolve()`](modules.html#requireresolverequest-options) and the [ES modules resolution algorithm](esm.html#resolution-algorithm)\nused by `import` and [`import.meta.resolve()`](esm.html#importmetaresolvespecifier) 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.\n\nBecause 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.\n\nFor resolution purposes the mount point behaves as a file system\nroot: `package.json` scope lookups and [loading from `node_modules`\nfolders](modules.html#loading-from-node_modules-folders) stop at the mount point. For example, when\n`${mountPoint}/foo/bar/main.cjs` calls `require('baz')`, the lookup\ngoes through:\n\n* `${mountPoint}/foo/bar/node_modules/baz`\n* `${mountPoint}/foo/node_modules/baz`\n* `${mountPoint}/node_modules/baz`\n* If `$NODE_PATH` is set, the folders listed in `$NODE_PATH`\n* `$HOME/.node_modules/baz`\n* `$HOME/.node_libraries/baz`\n* `$PREFIX/lib/node/baz`\n\nThe last four entries are [the global folders](modules.html#loading-from-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\n`require()` a real one.\n\n```cjs\nconst 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();\n```\n\nFor ECMAScript modules, use `file:` URLs when passing mounted paths\nto dynamic `import()`. [`vfs.mountPointURL`](#vfsmountpointurl) provides the mount\npoint in that form; this keeps VFS imports portable on Windows,\nwhere mounted paths use Windows path syntax.\n\n```mjs\nimport 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();\n```\n\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`.\n\nLike 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.\n\nCalling [`vfs.unmount()`](#vfsunmount) 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.\n\nMounting 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.\n\nNative addons (`.node` files) stored in a mounted VFS can be `require()`d as\nwell. The operating system's dynamic loader cannot open a virtual path, so the\naddon's bytes are read from the VFS and loaded from a private, self-cleaning\ntemporary image instead. Addons on the real file system are unaffected and\nload directly.\n\nShared libraries opened through [`ffi.dlopen()`](ffi.html#ffidlopenpath-definitions) (or\n[`new ffi.DynamicLibrary()`](ffi.html#new-dynamiclibrarypath)) work the same way: a library path inside a\nmounted VFS is detected, its bytes are read from the VFS, and the library is\nloaded from a private, self-cleaning image while `library.path` keeps\nreporting the virtual path. Libraries on the real file system load directly.","summary":"Once a `VirtualFileSystem` is mounted, paths under the mount point participate in module resolution and loading. The CommonJS resolution algorithm used by `require()` and `require.resolve()` and the ES modules resolution algorithm used by `import` and `import.meta.resolve()` are unchanged; instead, every file system operation those algorithms perform is dispatched on the path being probed: paths under a mount point are served by the owning VFS, and all other paths are served by the real file system. Files served from the VFS therefore behave as first-class modules.","examples":[{"language":"cjs","displayName":null,"code":"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();"},{"language":"mjs","displayName":null,"code":"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();"}],"children":[]},{"kind":"section","id":"use-with-single-executable-applications","name":"Use with Single Executable Applications","title":"Use with Single Executable Applications","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"When running as a [Single Executable Application](single-executable-applications.html) built with\n`\"useVfs\": true` in the SEA configuration, the bundled assets are\nautomatically mounted as a read-only virtual file system and the injected\nmain script is executed from the root of the mount. No additional setup is\nrequired. Since the mount point is reserved and chosen at runtime, bundled\ncode accesses the assets through `__dirname`-relative paths and relative\n`require()` calls rather than through a fixed path:\n\n```cjs\n// In the SEA main script, __dirname is the root of the mounted assets.\nconst fs = require('node:fs');\nconst path = require('node:path');\n\nconst config = JSON.parse(\n  fs.readFileSync(path.join(__dirname, 'config.json'), 'utf8'));\nconst template = fs.readFileSync(\n  path.join(__dirname, 'templates/index.html'), 'utf8');\n```\n\nESM entry points (`\"mainFormat\": \"module\"`) are supported: the main module\nis loaded from inside the mount through the ESM loader, and\n`import.meta.dirname` points at the mount root.\n\n`\"useVfs\"` cannot be used together with `\"useSnapshot\"` or `\"useCodeCache\"`.\nThe SEA configuration parser will error if either combination is detected.\n\nSee the [Single Executable Application](single-executable-applications.html) documentation for more information\non creating SEA builds with assets.","summary":"When running as a Single Executable Application built with `\"useVfs\": true` in the SEA configuration, the bundled assets are automatically mounted as a read-only virtual file system and the injected main script is executed from the root of the mount. No additional setup is required. Since the mount point is reserved and chosen at runtime, bundled code accesses the assets through `__dirname`-relative paths and relative `require()` calls rather than through a fixed path:","examples":[{"language":"cjs","displayName":null,"code":"// In the SEA main script, __dirname is the root of the mounted assets.\nconst fs = require('node:fs');\nconst path = require('node:path');\n\nconst config = JSON.parse(\n  fs.readFileSync(path.join(__dirname, 'config.json'), 'utf8'));\nconst template = fs.readFileSync(\n  path.join(__dirname, 'templates/index.html'), 'utf8');"}],"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":"class","id":"class-zipprovider","name":"ZipProvider","title":"Class: `ZipProvider`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"extends":null,"description":"A provider that exposes the entries of a ZIP archive - either a\n[`zlib.ZipBuffer`](zlib.html#class-zlibzipbuffer) (in memory) or a [`zlib.ZipFile`](zlib.html#class-zlibzipfile) (on disk) - through\nthe VFS API. `provider.readonly` reflects the archive's own\n[`zipFile.writable`](zlib.html#zipfilewritable) flag: a `ZipBuffer` is always writable, and a\n`ZipFile` is writable only when opened with `{ writable: true }`.\n\nDirectories 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.\n\nEvery method has a synchronous counterpart (`openSync()`, `statSync()`,\n`readdirSync()`, and so on), backed by the equally complete synchronous\nsurface [`zlib.ZipBuffer`](zlib.html#class-zlibzipbuffer)/[`zlib.ZipFile`](zlib.html#class-zlibzipfile) 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.\n\n```cjs\nconst 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```","summary":"A provider that exposes the entries of a ZIP archive - either a `zlib.ZipBuffer` (in memory) or a `zlib.ZipFile` (on disk) - through the VFS API. `provider.readonly` reflects the archive's own `zipFile.writable` flag: a `ZipBuffer` is always writable, and a `ZipFile` is writable only when opened with `{ writable: true }`.","examples":[{"language":"cjs","displayName":null,"code":"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();"}],"children":[{"kind":"constructor","id":"new-zipprovidersource","name":"ZipProvider","title":"`new ZipProvider(source)`","scope":"module","overloadOf":null,"stability":null,"added":["v26.9.0"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"source","type":{"text":"zlib.ZipBuffer | zlib.ZipFile","links":[{"name":"zlib.ZipBuffer","href":"zlib.html#class-zlibzipbuffer","start":0,"end":14},{"name":"zlib.ZipFile","href":"zlib.html#class-zlibzipfile","start":17,"end":29}]},"description":"An already-open archive.","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"","summary":"","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":[]}]}]}