sea: mount bundled assets as a virtual file system - #65675
Draft
mcollina wants to merge 2 commits into
Draft
Conversation
Collaborator
|
Review requested:
|
nodejs-github-bot
added
lib / src
mcollina
force-pushed
the
vfs-sea-integration
branch
2 times, most recently
from
August 31, 2026 09:13
7e3ed4b to
148a0d7
Compare
Add a "useVfs" boolean to the SEA configuration. When enabled, the bundled assets are mounted as a read-only virtual file system before the main script runs, and the main script is placed at the mount point root and executed from there via wrapModuleLoad. __filename, __dirname, relative require() calls, and node_modules lookups then all resolve against the bundled assets, confined to the mount. Since a VFS never shadows the real file system, bundled code reaches the assets through __dirname-relative paths instead of a fixed mount location. The new SEAProvider derives the directory tree from the asset keys and keeps asset content in the executable's SEA blob, copying it into JS memory only when a file is opened. The main script is not duplicated into the assets at build time; its source already lives in the blob and is injected into the provider at runtime. The implicit SEA mount does not emit the VirtualFileSystem experimental warning, which is already covered by the SEA warning. "useVfs" is rejected together with "useSnapshot", "useCodeCache", and "mainFormat": "module"; ESM entry points are left as future work. Signed-off-by: Matteo Collina <hello@matteocollina.com>
mcollina
force-pushed
the
vfs-sea-integration
branch
from
August 31, 2026 09:14
148a0d7 to
4991e64
Compare
Allow "mainFormat": "module" together with "useVfs": true. The ESM main script is placed at the mount point root like the CommonJS one, and loaded through the ESM loader via runEntryPointWithESMLoader, so import.meta.url, import.meta.filename, and import.meta.dirname reflect the location of the main module inside the virtual file system, and static imports, dynamic import(), and bare specifier lookups all resolve against the bundled assets. Signed-off-by: Matteo Collina <hello@matteocollina.com>
mcollina
requested review from
Qard and
joyeecheung
and removed request for
Qard
August 31, 2026 10:46
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds the SEA integration for the virtual file system landed in #63653: setting
"useVfs": truein the SEA configuration mounts the bundled assets as a read-only VFS and runs the injected main script from inside the mount.Since a VFS never shadows the real file system and its mount point is reserved and chosen at runtime, there is no fixed
/seapath. Instead, the main script is placed at the root of the mount and executed from there, so:__filenameand__dirnamepoint inside the virtual file system;__dirname-relative paths with regularnode:fsAPIs;require()calls andnode_moduleslookups resolve against the bundled assets, confined to the mount by the module loader integration.Implementation notes:
SEAProvideris read-only and lazy: asset content stays in the executable's SEA blob and is copied into JS memory only when a file is opened, with sizes cached forstat.VirtualFileSystemexperimental warning; the SEA warning already covers it."mainFormat": "module") are supported: the ESM main is loaded from inside the mount through the ESM loader, soimport.meta.url/filename/dirnamereflect the mount and static imports, dynamicimport(), and bare specifier lookups resolve against the bundled assets."useVfs"is rejected together with"useSnapshot"and"useCodeCache".This PR was prepared with the help of AI. I've reviewed all changes myself.