**decode-sourcemap-cli** is a local CLI tool that converts production minified error stack traces back into original source locations using sourcemaps — **fully offline**, without any backend server.
npm install decode-sourcemap-clidecode-sourcemap-cli is a local CLI tool that converts production minified error stack traces back into original source locations using sourcemaps — fully offline, without any backend server.
It is designed for environments where frontend debugging must happen locally, using only build artifacts.
Some environments operate under strict infrastructure or security constraints, such as:
- Financial institutions
- Government systems
- Internal corporate networks
- Intranet-only or isolated environments
In these setups, the following are often not allowed:
- ❌ Uploading .map files to a server
- ❌ Using external error monitoring services (Sentry, Datadog, etc.)
- ❌ Sending frontend logs outside the local machine
- ❌ Running backend APIs for sourcemap decoding
As a result, production errors often look like this:
```
at ExampleComponent-Cq_iF_Ko.js:1:120
at index-CWMXbtJ-.js:13:38
From this alone, developers cannot know:
- Which original .vue / .tsx file caused the error
- The real line and column number
- Whether the issue is in app code, framework code, or a library
Debugging becomes slow, manual, and error-prone.
decode-sourcemap-cli exists to solve this exact problem.
It enables:
- ✔️ Sourcemap decoding entirely on the developer machine
- ✔️ No backend server
- ✔️ No network access
- ✔️ No external services
- ✔️ Debugging using only local build outputs (dist/.js, .map)
> This tool turns your local machine into a safe, offline debugging environment for production errors.
A typical workflow looks like this:
1. Build the application locally (so you have JS bundles and sourcemaps).
2. Copy the error stack trace from the browser console or log output.
3. Run the CLI (dsm) and paste the logs when prompted..map
4. The CLI locates the corresponding files and decodes the stack trace.
The decoded result includes:
- Original source file path
- Line and column number
- Error classification (app / framework / library)
- Clickable file paths in the terminal
- Optional HTML report for sharing
The easiest and recommended way is to install it as a dev dependency and run via npx.
`bash`
npm add -D decode-sourcemap-clior
pnpm add -D decode-sourcemap-cli
Run:
`bash`
npx dsm
No global installation is required.
`bash`
npx dsm

If multiple apps are detected (e.g. monorepo), you will be prompted to select one.

The CLI determines the correct build output directory.

Paste the stack trace exactly as it appears in the browser or log output.

Minified positions are converted back into original source locations.

Paths are printed in a format that allows Command + Click (or Ctrl + Click).

| Option | Description |
|------|-------------|
| --html | Export decoded results as an HTML report |--strategy=
|
Example:
`bash`
npx dsm --html report.html
`bash`
npx dsm --strategy=strict
`bash`
npx dsm --strategy=filename
decode-sourcemap-cli supports multiple decoding strategies depending on how strictly
your local build artifacts match the production build.
This option exists because **sourcemap decoding accuracy fundamentally depends on
whether the build outputs are identical**.
#### ▶ strict (default, recommended)
`bash`
npx dsm --strategy=strict
Strict mode assumes that:
- The local build artifacts are generated from the same release as production
- JS bundle filenames (including hashes) match exactly
- The generated code structure is identical
In this mode, the CLI:
- Resolves the JS bundle by exact filename
- Uses sourcemaps with full line/column validation
- Fails safely if the bundle or sourcemap does not match
This is the most accurate and safest mode, and should be used whenever possible.
✅ Recommended when:
- You have access to the exact release build artifacts
- You keep build outputs per release
- You need guaranteed correct source locations
#### ▶ filename (best-effort, low confidence)
`bash`
npx dsm --strategy=filename
Filename mode is designed for cases where strict decoding is not possible.
Typical scenarios include:
- The production JS hash is not available locally
- You rebuilt the app from the same source, but hashes differ
- You still want a debugging hint, not guaranteed accuracy
In this mode, the CLI:
- Ignores hash differences in JS filenames
- Searches JS bundles by entry name only
(e.g. helloWorld.xxxxx.js → helloWorld)
- Attempts sourcemap decoding on the closest match
⚠️ Important limitations
- The decoded location may be inaccurate
- Line and column mappings can be offset
- Results are explicitly marked with a warning:
``
⚠️ Decoded using filename-based strategy.
This result may be inaccurate if build artifacts differ.
This mode should be treated as a debugging aid, not a source of truth.
✅ Useful when:
- You cannot reproduce the exact production build
- You need quick insight into which area of the code might be involved
- You understand and accept reduced accuracy
❌ Not recommended for:
- Incident reports
- Root-cause analysis
- Security or compliance documentation
#### ▶ Choosing the Right Strategy
| Situation | Recommended Strategy |
|---------|---------------------|
| Same release build available | strict |filename
| Hashes differ, source similar | |strict
| Compliance / audit debugging | |filename
| Quick exploratory debugging | |
> Note
> Sourcemaps are fundamentally designed to work with identical build outputs.
> The filename strategy intentionally relaxes this rule and should be used with caution.
This project provides guides for:
- Single App (no config)
- Single App + sourcemap.config.json
- Turborepo / Multi-app monorepo
Each guide explains how the CLI resolves apps and build outputs.
| Constraint | Typical Problem | Solution |
|-----------|----------------|----------|
| No backend APIs | Cannot decode server-side | Decode locally |
| No external network | SaaS unavailable | Zero network usage |
| Security compliance | Source exposure risk | Everything stays local |
decode-sourcemap-cli` provides:
- 🔒 100% offline sourcemap decoding
- 🧭 Clear, readable error locations
- 📂 Clickable navigation to source files
- 📝 Optional HTML reporting
- 🏗️ Support for single-app and monorepo setups