Course contentsShow
← Web Development
Lesson 2279 of 2,98241. Debugging TechniquesFree lesson

Source Map File Format and Structure

Learning the .map file format, the mappings field, and how browsers use source maps to reconstruct original code.

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: Always 3 (current spec)
  • sources: Array of original file paths
  • names: Variable/function names from your original code
  • mappings: Encoded string mapping generated code positions to original positions
  • file: The generated/compiled file this map describes
  • sourcesContent: 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.