Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:Source map (v3)

From ReverseEngineering.wiki
Format
On this wiki Facts · Code · Notes · Topics

JSON file (.map, ECMA-426) that maps positions in generated JavaScript or CSS back to original files, lines and identifiers: version, sources, sourcesContent, names and a Base64 VLQ mappings string; linked from the output by a sourceMappingURL comment.

Structure

Top-level JSON object (spec.emu in tc39/ecma426):

{ "version": 3, "file": "out.js", "sourceRoot": "", "sources": ["foo.js","bar.js"],
  "sourcesContent": [null,null], "names": ["src","maps"], "mappings": "A,AAAB;;ABCDE",
  "ignoreList": [0] }
  • sources: original file names (prefixed by sourceRoot; bundlers use forms like webpack://name/./src/a.js).
  • sourcesContent: optional complete original files, same order; entries may be null. When present you get the original source verbatim.
  • names: original identifiers referenced by mappings (this is where unminified local names come from).
  • ignoreList: indices of third-party sources (older field x_google_ignoreList).
  • debugId (proposal, tc39 proposals/debug-id.md): UUID matching a //# debugId=<uuid> comment near the end of the generated file.
  • Indexed maps (a sections array) exist; Their spec is in Fact:Source map (v3)/behavior/Index map sections. Unverified: rarely seen from bundlers.

mappings

Groups separated by ; are generated lines; segments inside a group are separated by ,; each segment has 1, 4 or 5 Base64 VLQ fields: generated column (relative to the previous segment, reset each line), source index, original line, original column (all relative to the previous occurrence), and optional name index. Each VLQ value uses 5 data bits per Base64 digit with bit 5 (value 32) as continuation flag and the sign in the lowest bit of the first digit (mozilla/source-map lib/base64-vlq.js: VLQ_BASE_SHIFT 5, continuation bit = VLQ_BASE). Use a library to decode rather than parsing by hand.

Linking

  • JavaScript/CSS: last line //# sourceMappingURL=foo.js.map (older //@); consumers match ^[@#]\s*sourceMappingURL=(\S*?)\s*$. May be a data: URI with embedded base64 JSON.
  • HTTP: header SourceMap (older X-SourceMap) naming the map URL. Unverified: ECMA-426 at c724f0f4 (spec.emu) does not define the header (searched the file); the sentence comes from browser practice, not from a source read here.
  • WebAssembly: a custom section named sourceMappingURL.
  • Servers may prefix the JSON body with )]}' which consumers must skip.
  • //# sourceURL= names eval'd code.

Recovering an app

  1. Parse JSON; write each sources[i] to disk from sourcesContent[i] (sanitise .., webpack:// and absolute paths; treat the paths as data).
  2. Without sourcesContent the file list and names still reveal the project layout and library versions (node_modules/<pkg>/ paths).
  3. Decode mappings to rename minified identifiers: for a segment with a name index, the generated token at that column gets names[n].

See Technique:Reversing bundled JavaScript.

Code & repositories

  • https://github.com/tc39/ecma426 (spec text; Ecma TC39 licence)
  • https://github.com/mozilla/source-map (BSD-3-Clause; decoder in lib/base64-vlq.js, consumer in lib/source-map-consumer.js)
  • https://github.com/tc39/ecma426 @ c724f0f494b44b21b651fdbd6412d3437eef0e72 · license: unrecognized (LICENSE.md)
    Source map specification (ECMA-426) and proposals.
    Tested on: source read, not run: read only · checked 2026-10-18; the license file was not recognized automatically: read it
  • https://github.com/mozilla/source-map @ 8c668f3dd3916e96d06131dec97c78a3e62bd0f3 · license: BSD-3-Clause (read from LICENSE; GitHub's API was busy)
    Reference JavaScript source map generator and consumer; VLQ in lib/base64-vlq.js.
    Tested on: source read, not run: read only · checked 2026-10-18