Format:Source map (v3)
| 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 bysourceRoot; bundlers use forms likewebpack://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 fieldx_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
sectionsarray) 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 adata:URI with embedded base64 JSON. - HTTP: header
SourceMap(olderX-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
- Parse JSON; write each
sources[i]to disk fromsourcesContent[i](sanitise..,webpack://and absolute paths; treat the paths as data). - Without sourcesContent the file list and
namesstill reveal the project layout and library versions (node_modules/<pkg>/paths). - 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