sourcemap-extract

Restore original source files from JavaScript/CSS source maps.

Implements ECMA-426 (1st edition, December 2024) — the official source map standard.

---

Quick start

# No install required
npx sourcemap-extract -o ./src dist/bundle.js.map

# Or install globally
npm install -g sourcemap-extract
sourcemap-extract -o ./src dist/bundle.js.map

---

CLI usage

sourcemap-extract [options] <input>

Inputs
  <file.map>          Any source map file
  <generated.js/css>  A bundled file with an embedded base64 sourceMappingURL
  <directory>         Recursively finds and processes every .map file inside
  -                   Reads source map JSON from stdin

Options

Flag	Description
-o, --out <dir>	Output directory (default: ./sourcemap-out)
-f, --force	Overwrite files that already exist
-n, --dry-run	Print what would be written without writing anything
-v, --verbose	Log every file path during extraction
--skip-ignored	Skip sources listed in ignoreList / x_google_ignoreList (third-party/node_modules code)
-h, --help	Show help

Examples

# Single map file
npx sourcemap-extract -o ./src dist/bundle.js.map

# Generated file with embedded sourceMappingURL
npx sourcemap-extract -o ./src dist/bundle.js

# Whole dist folder — processes every .map file recursively
npx sourcemap-extract -o ./src ./dist

# Preview without writing
npx sourcemap-extract --dry-run ./dist

# Skip third-party code (ignoreList)
npx sourcemap-extract --skip-ignored -o ./src dist/bundle.js.map

# Force overwrite + verbose
npx sourcemap-extract -f -v -o ./src dist/bundle.js.map

# stdin
cat bundle.js.map | npx sourcemap-extract -o ./src -

---

Programmatic API

const {
  parseSourceMap,    // parse JSON → source entries
  extractFromJson,   // extract to disk from JSON string
  extractFromFile,   // extract to disk from file path
  findMapFiles,      // recursively find .map files in a directory
  resolveSourceURL,  // resolve a single sourceRoot + source URL
  sanitizePath,      // sanitise a resolved path for safe disk writes
} = require('sourcemap-extract');

parseSourceMap(json)

Parse a source map JSON string. Returns an array of source entries.

const entries = parseSourceMap(fs.readFileSync('bundle.js.map', 'utf8'));
// [
//   { name: 'src/App.tsx', content: '...', ignored: false },
//   { name: 'src/utils.ts', content: '...', ignored: false },
//   { name: null, content: null, ignored: true },  // null-named source
// ]

Each entry:

Field	Type	Description
name	string | null	Resolved source path, or null if the sources entry was null
content	string | null	Original source text from sourcesContent, or null if absent
ignored	boolean	true if the index appears in ignoreList / x_google_ignoreList

extractFromJson(mapJson, outDir, options?)

Extract source files to disk from a raw JSON string.

const result = extractFromJson(mapJson, './src', {
  force      : false,  // overwrite existing files
  dryRun     : false,  // don't write, just report
  skipIgnored: false,  // skip ignoreList sources
  verbose    : false,  // log per-file activity
});

// result: { total, written, failed, skipped, noContent, ignored, planned?, error? }

In dryRun mode result.planned is an array of paths that would be written; result.written is always 0.

extractFromFile(filePath, outDir, options?)

Convenience wrapper — reads the file from disk first, then calls extractFromJson. Accepts .map/.json files or generated files with an embedded base64 sourceMappingURL.

findMapFiles(dir)

Recursively returns every .map file path inside dir (matches *.js.map, *.css.map, *.ts.map, *.wasm.map, *.map, …).

---

ECMA-426 compliance

Requirement	Status
sources entries may be null	✅
sourcesContent shorter than sources	✅
sourcesContent entries may be null	✅
ignoreList (standard field)	✅
x_google_ignoreList (deprecated alias)	✅
Sectioned maps ({ sections: [] })	✅
UTF-8 BOM stripping before JSON parse	✅
sourceRoot URL-style join (relative paths only)	✅

Bundler URL schemes stripped automatically

webpack://, webpack-internal:///, ng://, vite://, turbopack://[project]/, and any generic protocol://origin/ prefix.

---

Path safety

All output paths are sanitised before writing:

• Leading ../ traversal sequences removed
• Absolute paths (/…, C:\…) made relative
• Query strings and fragment identifiers stripped
• Duplicate source→destination collisions skipped (first wins)

No file is ever written outside the specified output directory.

---

License

MIT