SKILL.md
GitHubnode:vfs and VFS-backed single executables
| Feature | Versions | Stability | Flag |
|---|---|---|---|
node:vfs: create, MemoryProvider, RealFSProvider |
v26.4.0 | 1 | 26.x: --experimental-vfs; v27+: none (--no-experimental-vfs disables) |
mount/unmount/mountPointURL, ZipProvider, --allow-fs-vfs |
v26.9.0 | 1 / 1.1 | as above |
registerProvider, --vfs-load |
v26.10.0 | 1 | as above |
vfsBase() · ComposableProvider |
v26.11.0 · v26.12.0 | 1 | as above |
--build-sea |
v25.5.0 | 1.1 | none |
SEA "useVfs", "vfsArchive" |
v26.9.0 | 1.0 | none |
None of this exists on v24. Feature-detect with
node -e "require('node:vfs').create().mount" (plus --experimental-vfs on 26.x).
Experimental API. Before relying on these details, run the
node-experimental-checkskill's probe (ornode --versionplus a feature-detect one-liner) and check the docs for the installed version:https://nodejs.org/docs/<version>/api/<module>.html. If the installed version disagrees with this skill, the installed version wins.
Mount, then use ordinary fs/require/import
import vfs from 'node:vfs';
using v = vfs.create(); // MemoryProvider; unmounts at scope end
v.writeFileSync('/mod.mjs', 'export default 42'); // seed BEFORE mount
const root = v.mount(); // e.g. /dev/null/vfs/1 — never hard-code
fs.readFileSync(`${root}/mod.mjs`, 'utf8');
await import(`${v.mountPointURL}/mod.mjs`); // use the file: URL for import()
Code under test should take root as a parameter; VFS cannot fake fixed real
paths. Load from a zip: vfs.create(new vfs.ZipProvider(new zlib.ZipBuffer(bytes))),
or run a whole app: node --vfs-load=app.zip (runs its package.json "main").
Single executable with assets
sea-config.json: {"main":"main.js","output":"app","useVfs":true,"assets":{"config.json":"src/config.json"}},
then node --build-sea sea-config.json. Inside, __dirname is the read-only
mount root: fs.readFileSync(path.join(__dirname, 'config.json')),
require('./lib/x.js'). Or set "vfsArchive": "assets.zip" instead of assets.
Pitfalls
- While mounted, the instance's own methods need mount-prefixed paths too;
v.readFileSync('/a')throws ENOENT untilunmount(). - The mount is in-process: child processes,
fs.glob, andfs.cpdon't see it. Copying to the real fs fails withEXDEV. --permissionmakesmount()throwERR_INVALID_STATEwithout--allow-fs-vfs.- Not a sandbox:
RealFSProviderreads follow symlinks outside its root. --vfs-loadis rejected inNODE_OPTIONS. SEA:useVfsexcludesuseSnapshot;useCodeCache+useVfsneeds v27+;vfsArchiveneedsuseVfsand excludesassets.- With
vfsArchive,sea.getAsset()can't read the files. Use fs.
Don't
- Don't add
memfs/mock-fs/unionfswhere VFS fits (26.4+). Keep them for v24 and for faking fixed absolute paths. - Don't use
postjector--experimental-sea-configon 25.5+; use--build-sea. - Don't write SEA assets to a temp dir to
requirethem; useuseVfs.
Reference
- rules/api.md: read for the full VirtualFileSystem method list, providers, custom providers,
registerProvider, the reserved root, and module-loader rules. - rules/sea.md: read when writing a
--build-seaconfig: every field,useVfs/vfsArchive/code cache, workers, and validation errors. - rules/flags-security.md: read for flags per version,
--vfs-loaddetails, the permission model, and security limits.