From f3b744e7ef97a86eca853ff9899fcec38f6c8cce Mon Sep 17 00:00:00 2001 From: Matteo Collina Date: Sun, 15 Nov 2026 18:28:38 +0000 Subject: [PATCH] sea: add source maps for SEA with VFS SEA binaries built with "useVfs" can now load source maps from the bundled assets (or the "vfsArchive" archive) and apply them to stack traces and error output, because fs reads are routed through the virtual file system mounted by the SEA. Add two tests covering the inline-assets and zip-archive VFS paths, each asserting that findSourceMap() resolves against the mount point and that a thrown error's frame and source line are remapped to the original source. Also document how to enable and bundle source maps in a SEA. --- doc/api/single-executable-applications.md | 73 +++++++++++++++ test/fixtures/sea/vfs-sourcemap/original.js | 15 +++ .../sea/vfs-sourcemap/sea-config.json | 10 ++ test/fixtures/sea/vfs-sourcemap/sea.js | 16 ++++ test/fixtures/sea/vfs-sourcemap/sea.js.map | 12 +++ .../sea/vfs-zip-sourcemap/original.js | 15 +++ .../sea/vfs-zip-sourcemap/sea-config.json | 7 ++ test/fixtures/sea/vfs-zip-sourcemap/sea.js | 16 ++++ .../fixtures/sea/vfs-zip-sourcemap/sea.js.map | 12 +++ ...le-executable-application-vfs-sourcemap.js | 71 +++++++++++++++ ...xecutable-application-vfs-zip-sourcemap.js | 91 +++++++++++++++++++ 11 files changed, 338 insertions(+) create mode 100644 test/fixtures/sea/vfs-sourcemap/original.js create mode 100644 test/fixtures/sea/vfs-sourcemap/sea-config.json create mode 100644 test/fixtures/sea/vfs-sourcemap/sea.js create mode 100644 test/fixtures/sea/vfs-sourcemap/sea.js.map create mode 100644 test/fixtures/sea/vfs-zip-sourcemap/original.js create mode 100644 test/fixtures/sea/vfs-zip-sourcemap/sea-config.json create mode 100644 test/fixtures/sea/vfs-zip-sourcemap/sea.js create mode 100644 test/fixtures/sea/vfs-zip-sourcemap/sea.js.map create mode 100644 test/sea/test-single-executable-application-vfs-sourcemap.js create mode 100644 test/sea/test-single-executable-application-vfs-zip-sourcemap.js diff --git a/doc/api/single-executable-applications.md b/doc/api/single-executable-applications.md index 6bedb213b8ae..1be8bf4aba58 100644 --- a/doc/api/single-executable-applications.md +++ b/doc/api/single-executable-applications.md @@ -357,6 +357,75 @@ against its source, so it is used by the executable whenever the modules are loaded from the VFS, and ignored if they changed. The cache is platform-specific, like the code cache of the main script. +#### Source maps in the VFS + +[Source Map v3][] maps work in a SEA using `"useVfs": true` exactly as they do +on the real file system, provided the maps are bundled as assets (or inside +the `"vfsArchive"` archive) and source map support is enabled in the generated +executable. The `.map` file is read from inside the mount point, and the +`"sources"` of the map and the original sources are resolved against the mount +point too. As a result, [`module.findSourceMap()`][], source-mapped stack +traces, and the source line shown above an uncaught error all resolve against +the bundled assets rather than the real file system. + +Source maps are enabled in a SEA the same way as in a regular Node.js process +with [`--enable-source-maps`][]. The flag is not consumed when it is +passed as a command-line argument to the executable: with the default +`"execArgvExtension": "env"`, command-line arguments are handed to the +application. Set it in `"execArgv"` (or in [`NODE_OPTIONS`][]) instead: + +```json +{ + "main": "sea.js", + "output": "sea", + "useVfs": true, + "execArgv": ["--enable-source-maps"], + "assets": { + "sea.js.map": "dist/sea.js.map", + "original.js": "src/original.js" + } +} +``` + +The bundled source must end with a `sourceMappingURL` magic comment that points +at the map. A relative path resolves against the location of the script inside +the mount, so no mount-point path needs to be hard-coded: + +```cjs +// sea.js +'use strict'; + +function boom() { + throw new Error('boom from the original source'); +} + +boom(); +//# sourceMappingURL=sea.js.map +``` + +If the map embeds `sourcesContent`, the original source lines are taken from +the map itself. Otherwise the original sources must also be bundled (as +assets, or as entries in the `"vfsArchive"` archive) so that the error source +preview can be read back through the VFS, as in the configuration above. With +`--enable-source-maps` enabled, throwing the error above maps the stack frame +back to `original.js` and shows the original source line: + +```text +…/vfs/1/original.js:5 + throw new Error('boom from the original source'); + ^ + +Error: boom from the original source + at boom (…/vfs/1/original.js:5:5) +``` + +The `…` stands in for the reserved mount point, which is chosen at runtime and +cannot exist on the real file system. When the application is transpiled, the +bundler typically emits the map next to the bundled file; make sure to bundle +it with `"assets"` (or include it in the `"vfsArchive"` archive), because the +VFS never shadows the real file system and the `.map` file must therefore be +reachable inside the mount. + #### Snapshot limitations `"useVfs": true` cannot be used together with `"useSnapshot": true`. @@ -844,11 +913,15 @@ to help us document them. [Generating single executable preparation blobs]: #1-generating-single-executable-preparation-blobs [Mach-O]: https://en.wikipedia.org/wiki/Mach-O [PE]: https://en.wikipedia.org/wiki/Portable_Executable +[Source Map v3]: https://tc39.es/ecma426/ [Using native addons in the injected main script]: #using-native-addons-in-the-injected-main-script [VFS documentation]: vfs.md [Windows SDK]: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/ +[`--enable-source-maps`]: cli.md#--enable-source-maps [`--vfs-load`]: cli.md#--vfs-loadsource +[`NODE_OPTIONS`]: cli.md#node_optionsoptions [`Worker`]: worker_threads.md#class-worker +[`module.findSourceMap()`]: module.md#modulefindsourcemappath [`node:zlib`]: zlib.md [`process.execPath`]: process.md#processexecpath [`require()`]: modules.md#requireid diff --git a/test/fixtures/sea/vfs-sourcemap/original.js b/test/fixtures/sea/vfs-sourcemap/original.js new file mode 100644 index 000000000000..5d0c8cfbcb97 --- /dev/null +++ b/test/fixtures/sea/vfs-sourcemap/original.js @@ -0,0 +1,15 @@ +'use strict'; + +const { findSourceMap } = require('module'); + +const sm = findSourceMap(__filename); +if (sm === undefined) { + throw new Error('source map was not loaded from the SEA VFS'); +} +console.log('source map loaded from the SEA VFS:', sm.payload.sources[0]); + +function boom() { + throw new Error('boom from the original source'); +} + +boom(); diff --git a/test/fixtures/sea/vfs-sourcemap/sea-config.json b/test/fixtures/sea/vfs-sourcemap/sea-config.json new file mode 100644 index 000000000000..bf4c11610fb4 --- /dev/null +++ b/test/fixtures/sea/vfs-sourcemap/sea-config.json @@ -0,0 +1,10 @@ +{ + "main": "sea.js", + "output": "sea-prep.blob", + "useVfs": true, + "execArgv": ["--enable-source-maps"], + "assets": { + "sea.js.map": "sea.js.map", + "original.js": "original.js" + } +} diff --git a/test/fixtures/sea/vfs-sourcemap/sea.js b/test/fixtures/sea/vfs-sourcemap/sea.js new file mode 100644 index 000000000000..91e395e46eb5 --- /dev/null +++ b/test/fixtures/sea/vfs-sourcemap/sea.js @@ -0,0 +1,16 @@ +'use strict'; + +const { findSourceMap } = require('module'); + +const sm = findSourceMap(__filename); +if (sm === undefined) { + throw new Error('source map was not loaded from the SEA VFS'); +} +console.log('source map loaded from the SEA VFS:', sm.payload.sources[0]); + +function boom() { + throw new Error('boom from the original source'); +} + +boom(); +//# sourceMappingURL=sea.js.map diff --git a/test/fixtures/sea/vfs-sourcemap/sea.js.map b/test/fixtures/sea/vfs-sourcemap/sea.js.map new file mode 100644 index 000000000000..92f8dd817613 --- /dev/null +++ b/test/fixtures/sea/vfs-sourcemap/sea.js.map @@ -0,0 +1,12 @@ +{ + "version": 3, + "file": "sea.js", + "sources": [ + "original.js" + ], + "names": [ + "boom" + ], + "mappings": "AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACI;FACJ;AACA;AACA;AACA", + "sourceRoot": "" +} \ No newline at end of file diff --git a/test/fixtures/sea/vfs-zip-sourcemap/original.js b/test/fixtures/sea/vfs-zip-sourcemap/original.js new file mode 100644 index 000000000000..5d0c8cfbcb97 --- /dev/null +++ b/test/fixtures/sea/vfs-zip-sourcemap/original.js @@ -0,0 +1,15 @@ +'use strict'; + +const { findSourceMap } = require('module'); + +const sm = findSourceMap(__filename); +if (sm === undefined) { + throw new Error('source map was not loaded from the SEA VFS'); +} +console.log('source map loaded from the SEA VFS:', sm.payload.sources[0]); + +function boom() { + throw new Error('boom from the original source'); +} + +boom(); diff --git a/test/fixtures/sea/vfs-zip-sourcemap/sea-config.json b/test/fixtures/sea/vfs-zip-sourcemap/sea-config.json new file mode 100644 index 000000000000..d42121169ef3 --- /dev/null +++ b/test/fixtures/sea/vfs-zip-sourcemap/sea-config.json @@ -0,0 +1,7 @@ +{ + "main": "sea.js", + "output": "sea-prep.blob", + "useVfs": true, + "vfsArchive": "assets.zip", + "execArgv": ["--enable-source-maps"] +} diff --git a/test/fixtures/sea/vfs-zip-sourcemap/sea.js b/test/fixtures/sea/vfs-zip-sourcemap/sea.js new file mode 100644 index 000000000000..91e395e46eb5 --- /dev/null +++ b/test/fixtures/sea/vfs-zip-sourcemap/sea.js @@ -0,0 +1,16 @@ +'use strict'; + +const { findSourceMap } = require('module'); + +const sm = findSourceMap(__filename); +if (sm === undefined) { + throw new Error('source map was not loaded from the SEA VFS'); +} +console.log('source map loaded from the SEA VFS:', sm.payload.sources[0]); + +function boom() { + throw new Error('boom from the original source'); +} + +boom(); +//# sourceMappingURL=sea.js.map diff --git a/test/fixtures/sea/vfs-zip-sourcemap/sea.js.map b/test/fixtures/sea/vfs-zip-sourcemap/sea.js.map new file mode 100644 index 000000000000..92f8dd817613 --- /dev/null +++ b/test/fixtures/sea/vfs-zip-sourcemap/sea.js.map @@ -0,0 +1,12 @@ +{ + "version": 3, + "file": "sea.js", + "sources": [ + "original.js" + ], + "names": [ + "boom" + ], + "mappings": "AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACI;FACJ;AACA;AACA;AACA", + "sourceRoot": "" +} \ No newline at end of file diff --git a/test/sea/test-single-executable-application-vfs-sourcemap.js b/test/sea/test-single-executable-application-vfs-sourcemap.js new file mode 100644 index 000000000000..e54b4c60e796 --- /dev/null +++ b/test/sea/test-single-executable-application-vfs-sourcemap.js @@ -0,0 +1,71 @@ +'use strict'; + +// This tests that source maps are correctly loaded from a Single Executable +// Application when "useVfs" is enabled. The `.map` file and the original +// sources are bundled as `"assets"` and served from inside the read-only +// virtual file system mounted by the SEA, so `findSourceMap()` and the +// source-mapped stack trace must resolve against the mount point instead of +// the real file system. +// +// The fixture (`test/fixtures/sea/vfs-sourcemap/`) enables source maps through +// `execArgv` (`--enable-source-maps`), verifies that `module.findSourceMap()` +// finds the bundled map, and then throws an error. This test asserts that: +// 1. the mapped stack trace for the throw frame references the ORIGINAL +// source (`original.js`) rather than the generated `sea.js`, and +// 2. the original source line shown above the error is read back from the +// VFS (it carries the original 4-space indentation, not the 2-space +// indentation of the generated `sea.js`). +// +// The fixture's `sea.js.map` is a source-map-v3 identity mapping that is tied +// to the current content of `sea.js` and `original.js`: most lines are mapped +// one-to-one, and the `throw` line maps its column from 2 (the generated +// 2-space indentation) to 4 (the original 4-space indentation). If either +// fixture source is edited, regenerate the map so the columns stay in sync. + +require('../common'); + +const { + buildSEA, + skipIfBuildSEAIsNotSupported, +} = require('../common/sea'); + +skipIfBuildSEAIsNotSupported(); + +const tmpdir = require('../common/tmpdir'); +const { spawnSyncAndAssert } = require('../common/child_process'); +const fixtures = require('../common/fixtures'); + +tmpdir.refresh(); +const outputFile = buildSEA(fixtures.path('sea', 'vfs-sourcemap')); + +spawnSyncAndAssert( + outputFile, + { + env: { + ...process.env, + NODE_DEBUG_NATIVE: undefined, + }, + }, + { + // The SEA main script throws an uncaught error to produce the + // source-mapped stack trace. + status: 1, + stdout: /source map loaded from the SEA VFS: .*\/original\.js/, + stderr(stderr) { + // The throw frame must be remapped to the original source bundled in + // the VFS. Its column (5) matches the original 4-space indentation. + if (!/at boom \(.*\/original\.js:\d+:\d+\)/.test(stderr)) { + throw new Error(`the boom() frame was not source-mapped:\n${stderr}`); + } + // It must not still point at the generated sea.js. + if (/at boom \(.*\/sea\.js:\d+:\d+\)/.test(stderr)) { + throw new Error(`the boom() frame was not remapped to original.js:\n${stderr}`); + } + // The original source line is read from the VFS, so it shows the + // original 4-space indentation (the generated sea.js uses 2 spaces). + if (!/^ {4}throw new Error\('boom from the original source'\);$/m.test(stderr)) { + throw new Error(`the original source line was not read from the VFS:\n${stderr}`); + } + }, + }, +); diff --git a/test/sea/test-single-executable-application-vfs-zip-sourcemap.js b/test/sea/test-single-executable-application-vfs-zip-sourcemap.js new file mode 100644 index 000000000000..f9e6eed46a00 --- /dev/null +++ b/test/sea/test-single-executable-application-vfs-zip-sourcemap.js @@ -0,0 +1,91 @@ +'use strict'; + +// This tests that source maps are correctly loaded from a Single Executable +// Application when the assets are served from a ZIP archive mounted through +// the VFS (`"vfsArchive"`). The `.map` file and the original sources live in +// the archive and are served from the mount point, so `findSourceMap()` and +// the source-mapped stack trace must resolve against the mount point instead +// of the real file system. +// +// The fixture (`test/fixtures/sea/vfs-zip-sourcemap/`) enables source maps +// through `execArgv` (`--enable-source-maps`), verifies that +// `module.findSourceMap()` finds the bundled map, and then throws an error. +// This test asserts that the throw frame is remapped to the ORIGINAL source +// (`original.js`) in the archive and that the original source line (with its +// original 4-space indentation) is read back from the VFS. +// +// The fixture's `sea.js.map` is a source-map-v3 identity mapping that is tied +// to the current content of `sea.js` and `original.js`: most lines are mapped +// one-to-one, and the `throw` line maps its column from 2 (the generated +// 2-space indentation) to 4 (the original 4-space indentation). If either +// fixture source is edited, regenerate the map so the columns stay in sync. + +const common = require('../common'); + +const { + buildSEA, + skipIfBuildSEAIsNotSupported, +} = require('../common/sea'); + +skipIfBuildSEAIsNotSupported(); + +const tmpdir = require('../common/tmpdir'); +const { spawnSyncAndAssert } = require('../common/child_process'); +const fixtures = require('../common/fixtures'); +const { createWriteStream } = require('fs'); +const { pipeline } = require('stream/promises'); +const { zipFiles } = require('zlib'); + +// Asserts that the SEA stderr contains a source-mapped stack trace for an +// error thrown in `boom()`. +function assertSourceMappedStderr(stderr) { + // The throw frame must be remapped to the original source in the VFS. + if (!/at boom \(.*\/original\.js:\d+:\d+\)/.test(stderr)) { + throw new Error(`the boom() frame was not source-mapped:\n${stderr}`); + } + // It must not still point at the generated sea.js. + if (/at boom \(.*\/sea\.js:\d+:\d+\)/.test(stderr)) { + throw new Error(`the boom() frame was not remapped to original.js:\n${stderr}`); + } + // The original source line is read from the VFS, so it shows the original + // 4-space indentation (the generated sea.js uses 2 spaces). + if (!/^ {4}throw new Error\('boom from the original source'\);$/m.test(stderr)) { + throw new Error(`the original source line was not read from the VFS:\n${stderr}`); + } +} + +async function main() { + tmpdir.refresh(); + + // Build the assets archive with the ZIP support of node:zlib. This is what + // "vfsArchive" users do themselves before running --build-sea. + const fixture = (...args) => fixtures.path('sea', 'vfs-zip-sourcemap', ...args); + await pipeline( + zipFiles([ + [fixture('sea.js.map'), 'sea.js.map'], + [fixture('original.js'), 'original.js'], + ]), + createWriteStream(tmpdir.resolve('assets.zip')), + ); +} + +main().then(common.mustCall(() => { + const outputFile = buildSEA(fixtures.path('sea', 'vfs-zip-sourcemap')); + + spawnSyncAndAssert( + outputFile, + { + env: { + ...process.env, + NODE_DEBUG_NATIVE: undefined, + }, + }, + { + // The SEA main script throws an uncaught error to produce the + // source-mapped stack trace. + status: 1, + stdout: /source map loaded from the SEA VFS: .*\/original\.js/, + stderr: assertSourceMappedStderr, + }, + ); +}));