Appxiom Web Map

@appxiom/web-map is a local command-line tool for resolving JavaScript stack traces against source maps from a production build. The executable is appxiom-stacktrace.

Installation

Run it without a global install:

npx @appxiom/web-map "TypeError: Something went wrong
    at a (https://example.com/assets/index-abc123.js:1:3)" --maps ./dist

The default map directory is ./dist, relative to the current working directory, so --maps can be omitted when that is where the build files are located.

Usage

Pass a stack trace as one quoted argument or with --stacktrace:

npx @appxiom/web-map "TypeError: Something went wrong
    at a (https://example.com/assets/index-abc123.js:1:3)"

npx @appxiom/web-map --stacktrace "TypeError: Something went wrong
    at a (https://example.com/assets/index-abc123.js:1:3)" --maps ./dist

Read a stack trace from a file or standard input:

npx @appxiom/web-map --stacktrace-file ./error.txt --maps ./dist
cat ./error.txt | npx @appxiom/web-map --stdin --maps ./dist

The stack-trace text option is always literal text. Use --stacktrace-file when the input is a path.

| Option | Description | | --- | --- | | [text] | Stack trace as one quoted argument | | --stacktrace <text> | Literal stack-trace text | | --stacktrace-file <path> | Read stack trace from a file | | --stdin | Read stack trace from standard input | | --maps <directory-or-file> | Local map directory or a specific .map file; defaults to ./dist | | --json | Write the original input, resolved output, and frame statuses as JSON | | --verbose | Write selected maps and unresolved-frame explanations to stderr | | --help | Show command help | | --version | Show the package version |

Choose exactly one stack-trace input method. Normal output is written to stdout; diagnostics and errors go to stderr.

Supported Stack Traces

The parser supports Chrome and Chromium named and anonymous frames, Firefox function@file:line:column frames, and Safari-compatible function@file:line:column frames. It keeps exception messages, non-frame lines, and frame ordering. Frames without a safe local map association or a matching source-map entry remain unchanged.

Source-map version 3 files are supported, including maps with file, sourceRoot, sources, names, and sourcesContent fields. Maps may be adjacent to a generated bundle or referenced by its sourceMappingURL comment. Base64 inline JSON maps are also supported. Hashed bundle names and nested build directories are supported when their generated paths can be matched safely.

Function names are taken from source-map data when available. Otherwise the original stack-frame function name is kept; no source locations or names are fabricated.

JSON Output

--json writes one JSON object with the original input, reconstructed output, per-frame generated and resolved locations, status, optional unresolved reason, selected mapPath, and diagnostics. The sourcesContent values from a map are not included.

Local Processing and Privacy

All processing happens on the machine running the CLI. It does not make network requests, fetch remote maps, send telemetry, upload stack traces or maps, or execute generated bundles. A remote script URL in a stack frame is only used to identify a corresponding local bundle and map.

Troubleshooting

• If a frame stays unchanged, confirm the corresponding generated bundle and source map are inside the selected map directory, then use --verbose to see why it was not resolved.
• If several bundles have the same name, provide a map directory whose local paths preserve enough of the generated URL path to distinguish them.
• If the map is separate from its bundle, make sure its file field identifies the generated bundle and that the map directory contains both files.
• Remote sourceMappingURL values are not fetched. Copy the map into the local build directory and use a local reference.
• Use --help to check for conflicting input options and valid command syntax.

Local Development

The package requires Node.js 18 or later and uses npm:

npm install
npm test
npm run pack:dry-run

The test suite uses deterministic local fixtures and does not require network access at runtime. The package is not published by these commands.