vfs: add --vfs-mount and --vfs-load startup flags by pipobscure · Pull Request #65748 · nodejs/node

pipobscure · 2026-09-02T19:15:33Z

vfs: add --vfs-mount and --vfs-load startup flags

Mounting a virtual file system requires calling vfs.mount() from inside the
program, so a program cannot itself be served from one — something already
running has to mount the VFS first.

This adds two startup flags:

--vfs-mount=<source> mounts a directory or an archive as a virtual file
system. May be repeated.
--vfs-load=<source> mounts <source> exactly as --vfs-mount does, and
additionally runs the entry point and all subsequent require()/import
resolution against that mount rather than the real file system.

Together they let an application run straight out of a directory or a ZIP
archive:

$ node --experimental-vfs --vfs-load=my-app.zip

Mount order

Both options append to one list, so mounts happen in the order written:

$ node --experimental-vfs --vfs-mount=a --vfs-load=b --vfs-mount=c

mounts a, b and c in that order and runs b. Mounting the same source
twice mounts it twice, at two separate mount points; the entry point comes from
the mount --vfs-load contributed, not from an earlier --vfs-mount of the
same source.

Choosing a provider

The provider backing a source is chosen from the source itself rather than from
its file name: a directory is served by RealFSProvider, and a file whose bytes
are a ZIP archive by ZipProvider, so an archive can carry any extension.
vfs.registerProvider() registers a provider for formats there is no built-in
for. Selection is deferred until -r and --import preloads have run, so a
preloaded module can register one before its source is claimed.

Entry point and arguments

The entry point is taken from the mount the same way node <directory> takes
one: the mount's own package.json "main", or index.js. Because the entry
point comes from the mount, no positional argument is consumed as one — every
positional reaches the program unchanged from argv[2] onward. process.argv[1]
reports the named source rather than the reserved mount point, which is an
opaque implementation detail.

Constraints

--vfs-load may be given at most once; a second is rejected at startup.
--vfs-load is not permitted in NODE_OPTIONS: which entry point runs is the
command line's decision, and NODE_OPTIONS is parsed first, so an environment
variable could otherwise redirect any invocation. --vfs-mount is permitted
there and its mounts precede the command line's.
Workers inherit the same mounts in the same order, but not the loading: a
worker mounts what the parent mounted and runs its own entry point.
Both flags require --experimental-vfs.

Notes for reviewers

--vfs-mount and --vfs-load share one vfs_mounts list so ordering is
preserved by construction; a bracketed internal boolean set via Implies()
records that a load was requested, and which entry it contributed is recovered
from execArgv.
The vfs options are validated after all option sources are parsed rather than
in EnvironmentOptions::CheckOptions(), which runs at the end of every parse —
otherwise NODE_OPTIONS=--vfs-mount=x node --experimental-vfs is rejected for
an --experimental-vfs that has not been read yet.
Native addon loading from a mount is deliberately not included; it is proposed
separately and is independent of this change.

For context what this gives us see bundling tools and slides

nodejs-github-bot · 2026-09-02T19:15:39Z

Review requested:

@nodejs/config
@nodejs/loaders
@nodejs/startup
@nodejs/tsc

The zip support in node:zlib is released (v26.8.0) and ZipProvider merged today as nodejs/node#64915, so the old framing — "three things that are not in any release", pointing at #64339 and pipobscure/node#3 — was wrong in both directions: it undersold what has landed and misnamed what has not. What is actually outstanding is nodejs/node#65748, the --vfs-mount / --vfs-load flags and the vfs.registerProvider() that ships with them, plus nodejs/node#65680 for loading native addons out of a mount. Reading those two turned up semantics this repo's prose had wrong: --vfs-load runs the *first* mount (or --vfs-load=<index>), not the last; --vfs-mount takes no target, since node assigns a reserved mount point; argv[1] is the mounted source's real path rather than the mount point; and registered providers are now offered directories as well as files, which retires the constraint that made tools/observe.ts a runner rather than a preload. The deck's status slide said "This is in Node" with the flags marked as landed. It now says "landing", carries the two open PRs and the addon work as their own rows, and the speaker notes say plainly that the keystone is still a pull request. Deck republished to the artifact link in the README.

nodejs/node#65748 changed the flag on 2 Sep: --vfs-load used to select one of the --vfs-mount sources by 0-based index, which meant counting mounts out by hand and an optional-valued flag the options parser could only express as an alias onto a hidden --vfs-load-index. It now takes the source itself and mounts it, so `--vfs-load --vfs-mount X` is gone and `--vfs-load=X` does both. The launcher prefix was the breaking part: shell-base still exec'd node with the two-flag form, which a current build rejects outright with "--vfs-load requires an argument", so every archive signed with --launcher would have failed to run. It is now `--vfs-load="$0"`, and 77 bytes rather than 89. mountArgv() and the test helper follow, along with the command lines in the comments, the README, HISTORY, the deck and the release workflow's header. Two consequences worth recording rather than only fixing: the self-mounting shebang is one flag now, since the kernel-appended path becomes --vfs-load's value, and NODE_OPTIONS mounts sort before the command line's rather than after, because with no index to protect the order cannot change what runs. Verified against a node built from that branch (v27.0.0-pre): the whole suite passes, 136 of 136, and a signed launcher runs by name with dash-leading arguments reaching the program. While in there: tools/observe.ts explained itself with a constraint that no longer holds — registered providers are offered directories too — so it now gives the real reason it is a runner, which is that it wants the mount point.

codecov · 2026-09-03T12:41:02Z

Codecov Report

❌ Patch coverage is 92.95775% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.62%. Comparing base (4e207b1) to head (0c4f4fc).
⚠️ Report is 67 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node.cc	73.33%	4 Missing and 4 partials ⚠️
lib/internal/process/pre_execution.js	94.82%	4 Missing and 2 partials ⚠️
lib/internal/vfs/provider_registry.js	93.68%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65748      +/-   ##
==========================================
+ Coverage   89.95%   90.62%   +0.66%     
==========================================
  Files         759      771      +12     
  Lines      258637   269564   +10927     
  Branches    49015    55308    +6293     
==========================================
+ Hits       232665   244281   +11616     
+ Misses      17018    16480     -538     
+ Partials     8954     8803     -151

Files with missing lines	Coverage Δ
lib/internal/errors.js	`99.06% <100.00%> (+0.59%)`	⬆️
lib/internal/main/worker_thread.js	`95.02% <100.00%> (+0.11%)`	⬆️
lib/internal/modules/run_main.js	`100.00% <100.00%> (+2.35%)`	⬆️
lib/vfs.js	`100.00% <100.00%> (ø)`
src/node_options.cc	`87.23% <100.00%> (+7.74%)`	⬆️
src/node_options.h	`94.09% <100.00%> (-1.32%)`	⬇️
src/node_worker.cc	`88.94% <100.00%> (+7.49%)`	⬆️
lib/internal/process/pre_execution.js	`97.59% <94.82%> (+0.56%)`	⬆️
lib/internal/vfs/provider_registry.js	`93.68% <93.68%> (ø)`
src/node.cc	`80.21% <73.33%> (+3.64%)`	⬆️

... and 89 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Mounting a virtual file system requires calling vfs.mount() from inside the program, so a program cannot itself be served from one: something already running has to mount the VFS first. Add two startup flags. --vfs-mount=<source> mounts a directory or an archive as a virtual file system, and may be repeated. --vfs-load=<source> mounts that source the same way and additionally runs the entry point and all subsequent require()/import resolution against it rather than against the real file system, so an application can be run straight out of a directory or a ZIP archive: node --experimental-vfs --vfs-load=my-app.zip Both options append to one list, so mounts happen in the order written: node --experimental-vfs --vfs-mount=a --vfs-load=b --vfs-mount=c mounts a, b and c in that order and runs b. Mounting the same source twice mounts it twice, at two mount points, and the entry point comes from the mount --vfs-load contributed rather than the earlier one. The provider backing a source is chosen from the source itself rather than from its name: a directory is served by RealFSProvider and a file whose bytes are a ZIP archive by ZipProvider, so an archive can carry any extension. vfs.registerProvider() registers a provider for formats there is no built-in for; selection is deferred until -r and --import preloads have run, so a preloaded module can register one before its source is claimed. The entry point comes from the mount the way `node <directory>` takes one, from package.json "main" or index.js. Nothing is consumed as an entry point argument, so every positional reaches the program unchanged from argv[2] on, and argv[1] reports the named source rather than the reserved mount point, which is an opaque implementation detail. --vfs-load may be given at most once, and is not permitted in NODE_OPTIONS: which entry point runs is the command line's decision, and NODE_OPTIONS is parsed first, so an environment variable could otherwise redirect any invocation. --vfs-mount is permitted there. Workers inherit the same mounts in the same order but not the loading: a worker mounts what the parent mounted and runs its own entry point. Signed-off-by: Philipp Dunkel <pip@pipobscure.com>

pipobscure · 2026-09-03T12:55:41Z

Rebased because of documentation conflict.

mcollina

lgtm

mcollina · 2026-09-03T13:07:07Z

As per our practice and documentation those should be --experimental prefixed. I know it's ugly, but I think we need to follow that.

pipobscure · 2026-09-03T13:35:27Z

As per our practice and documentation those should be --experimental prefixed. I know it's ugly, but I think we need to follow that.

They are already behind --experimental-vfs to begin with, so does that still hold? Happy to oblige if so, just double checking.

Precedence: It's --allow-vfs-fs and not --experimental-allow-vfs-fs

pipobscure · 2026-09-04T14:46:43Z

it looks like there is something on CI that‘s repeating to fail. can someone let me know where that is and if there is something I can do about it?

nodejs-github-bot · 2026-09-04T18:44:37Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76990/

The module loader manufactures paths under the reserved VFS root that no layer owns: resolving a mount point as a directory first probes the sibling names `<mount>.js`, `<mount>.json` and `<mount>.node`, and a package.json walk-up passes the parents of the mount point. The lookup declined those because their layer segment is not a plain id, so they fell through to the native loader and the real file system. On POSIX that is harmless (ENOTDIR under /dev/null), but on Windows the root sits under `\\.\nul`, and `\\.\nul\<anything>` opens the NUL device: libuv reports it as a character device and a read returns nothing. The loader therefore picked `\\.\nul\vfs\<id>.js` as an existing file, and the native walk-up above it then read the device as an empty package.json and failed with ERR_INVALID_PACKAGE_CONFIG for `\\.\nul\package.json`. Any require() of a mount point hits this on Windows. Distinguish "under the root but unowned" from "outside the root" in the lookup and have every loader override report the former as not found: stat gives ENOENT, reads and realpath throw ENOENT, the package.json lookups return their "no package.json" results, and upward walks stop at the reserved root. Paths outside the root still go to the native loader as before. Refs: nodejs#65748 Signed-off-by: Philipp Dunkel <pip@pipobscure.com>

pipobscure · 2026-09-05T16:11:56Z

It looks like the CI for this exercises the path fixed in #65814 so this PRs CI depends on being rebased on that.

nodejs-github-bot added lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. labels Sep 2, 2026

jasnell reviewed Sep 2, 2026

View reviewed changes

Comment thread doc/api/cli.md Outdated

pipobscure force-pushed the vfsload branch from 0f8539b to 65957c3 Compare September 2, 2026 20:05

pipobscure force-pushed the vfsload branch from 3dab3a4 to bd9fc12 Compare September 3, 2026 09:51

pipobscure force-pushed the vfsload branch from bd9fc12 to 0c4f4fc Compare September 3, 2026 12:51

mcollina approved these changes Sep 3, 2026

View reviewed changes

mcollina added the request-ci Add this label to start a Jenkins CI on a PR. label Sep 3, 2026

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Sep 3, 2026

This comment was marked as outdated.

Sign in to view

jasnell approved these changes Sep 3, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

pipobscure force-pushed the vfsload branch from 0c4f4fc to b57b604 Compare September 5, 2026 14:38

pipobscure force-pushed the vfsload branch 2 times, most recently from 87aee89 to 0c4f4fc Compare September 5, 2026 15:23

Navigation Menu

Uh oh!

Uh oh!

vfs: add --vfs-mount and --vfs-load startup flags - #65748

vfs: add --vfs-mount and --vfs-load startup flags#65748
pipobscure wants to merge 1 commit into
nodejs:mainfrom
pipobscure:vfsload

pipobscure commented Sep 2, 2026 •

edited

Loading

Uh oh!

nodejs-github-bot commented Sep 2, 2026

Uh oh!

Uh oh!

codecov Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

pipobscure commented Sep 3, 2026

Uh oh!

mcollina left a comment

Uh oh!

mcollina commented Sep 3, 2026

Uh oh!

This comment was marked as outdated.

pipobscure commented Sep 3, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

pipobscure commented Sep 4, 2026

Uh oh!

nodejs-github-bot commented Sep 4, 2026

Uh oh!

pipobscure commented Sep 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Uh oh!

Conversation

pipobscure commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Mount order

Choosing a provider

Entry point and arguments

Constraints

Notes for reviewers

Uh oh!

nodejs-github-bot commented Sep 2, 2026

Uh oh!

Uh oh!

codecov Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pipobscure commented Sep 3, 2026

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

mcollina commented Sep 3, 2026

Uh oh!

This comment was marked as outdated.

pipobscure commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

pipobscure commented Sep 4, 2026

Uh oh!

nodejs-github-bot commented Sep 4, 2026

Uh oh!

pipobscure commented Sep 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pipobscure commented Sep 2, 2026 •

edited

Loading

codecov Bot commented Sep 3, 2026 •

edited

Loading

pipobscure commented Sep 3, 2026 •

edited

Loading