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