Source Map File Format and Structure
You'll learn how source map files are structured internally, what the cryptic mappings field means, and how browsers decode them to reconstruct your original code.
What Is a Source Map File?
A source map is a JSON file (typically with a .map extension) that acts like a translation dictionary between minified/transpiled code and your original source. When you open DevTools and see your original TypeScript or unminified JavaScript instead of the compiled mess, the browser is reading this file behind the scenes.
The Core Structure
A typical .map file contains:
{
"version": 3,
"sources": ["original.js", "utils.js"],
"names": ["myFunction", "counter", "result"],
"mappings": "AAAA,SAASA,EAAW;AACpB,IAAIC,EAAU",
"file": "bundle.min.js",
"sourcesContent": ["...original code..."]
}
version: Always3(current spec)sources: Array of original file pathsnames: Variable/function names from your original codemappings: Encoded string mapping generated code positions to original positionsfile: The generated/compiled file this map describessourcesContent: Optional embedded original source code
The Mappings Field: The Magic Decoder Ring
The mappings field looks like gibberish—it's Base64 VLQ-encoded (Variable Length Quantity). Each segment represents:
- Generated code line/column
- Original source file index
- Original line/column
- Original name index
Semicolons separate lines; commas separate segments within a line. Browsers decode this efficiently to map every position in your minified code back to the exact spot in your original source.
Think of it like subtitles: each timestamp (generated position) points to specific dialogue (original code).
Key Takeaway: Source maps are structured JSON files where the cryptic mappings field uses Base64 VLQ encoding to efficiently store position relationships, allowing browsers to reconstruct original code from compiled output during debugging.