Source maps in depth

What a source map holds

A source map links the code a browser runs back to the code you wrote. The bundlers lesson introduced it. This lesson takes one apart, the way DevTools and error trackers read it. Today the format is a standard of its own, ECMA-426.

Here is a file you wrote, and what a minifier made of it:

function addTax(price) {
  return price * 1.2;
}

function t(n){return n*1.2}

And here is the map between them, with its parts printed:

const map = {
  version: 3,
  file: "cart.min.js",
  sources: ["cart.js"],
  sourcesContent: ["function addTax(price) {\n  return price * 1.2;\n}\n"],
  names: ["addTax", "price"],
  mappings: "AAAA,SAASA,EAAOC,GACd,OAAOA",
};

console.log(map.mappings.split(";").length + " generated line");
console.log(map.mappings.split(",").length + " segments");
console.log(map.names.join(", "));

Line 4 lists the original files, and line 5 holds their code. Line 6 keeps the names the minifier replaced: t was addTax, and n was price. Line 7 is the part that does the real work.

It prints 1 generated line, 5 segments and addTax, price. Each segment links one place in the generated code to one place in cart.js.

Read each row of the table as: "this field holds this."

Base64 VLQ: numbers as letters

mappings stores numbers as letters, to keep maps small. Each letter is one of 64 characters, so it holds 6 bits. This is Base64 VLQ: variable-length quantity, because a big number can take several letters.

const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";

function encode(value) {
  let vlq = value < 0 ? (-value << 1) | 1 : value << 1;
  let out = "";
  do {
    let digit = vlq & 31;
    vlq >>>= 5;
    if (vlq > 0) digit |= 32;
    out += chars[digit];
  } while (vlq > 0);
  return out;
}

function decode(text) {
  const values = [];
  let value = 0;
  let shift = 0;
  for (const char of text) {
    const digit = chars.indexOf(char);
    value += (digit & 31) << shift;
    if (digit & 32) {
      shift += 5;
    } else {
      values.push(value & 1 ? -(value >>> 1) : value >>> 1);
      value = 0;
      shift = 0;
    }
  }
  return values;
}

console.log(encode(9), encode(-14), encode(1000));
console.log(decode("w+Bd").join(" "));

Line 4 makes room for the sign: the number is doubled, and the lowest bit is set when it is negative. Lines 6 to 11 write it 5 bits at a time, lowest first. Line 9 adds 32, the sixth bit, when more letters follow.

Lines 15 to 31 undo it. Line 21 adds each letter's 5 data bits at the right place. When a letter has no 32 bit, line 25 halves the number and uses the lowest bit as its sign.

Line 33 prints S d w+B: 9 needs one letter, -14 one letter, and 1000 three. Line 34 decodes w+Bd back into 1000 -14.

1const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";2 3function encode(value) {4  let vlq = value < 0 ? (-value << 1) | 1 : value << 1;5  let out = "";6  do {7    let digit = vlq & 31;8    vlq >>>= 5;9    if (vlq > 0) digit |= 32;10    out += chars[digit];11  } while (vlq > 0);12  return out;13}14 15function decode(text) {16  const values = [];17  let value = 0;18  let shift = 0;19  for (const char of text) {20    const digit = chars.indexOf(char);21    value += (digit & 31) << shift;22    if (digit & 32) {23      shift += 5;24    } else {25      values.push(value & 1 ? -(value >>> 1) : value >>> 1);26      value = 0;27      shift = 0;28    }29  }30  return values;31}32 33console.log(encode(9), encode(-14), encode(1000));34console.log(decode("w+Bd").join(" "));Run

Press Step to watch each letter add its bits to value, and see where a number ends. This replays the example code; it isn't a view inside the JavaScript engine.

Reading mappings: lines, segments and fields

A ; in mappings starts the next generated line, and a , starts the next segment on the same line. Each segment has 1, 4 or 5 numbers:

1. the generated column;
2. which file in sources;
3. the original line;
4. the original column;
5. which name in names, if the code was renamed.

Every number is the change from the segment before, not a full position. Changes are usually small, so they take fewer letters. The generated column starts again from 0 on each new line.

// The five segments of "AAAA,SAASA,EAAOC,GACd,OAAOA", already turned into numbers.
const relative = [
  [0, 0, 0, 0],
  [9, 0, 0, 9, 0],
  [2, 0, 0, 7, 1],
  [3, 0, 1, -14],
  [7, 0, 0, 7, 0],
];

let column = 0;
let line = 0;
let originalColumn = 0;
for (const fields of relative) {
  column += fields[0];
  line += fields[2];
  originalColumn += fields[3];
  console.log("column " + column + " -> line " + line + ", column " + originalColumn);
}

Lines 3 to 7 are the five segments of our map, decoded. Lines 14 to 16 add each change to a running total, and line 17 prints the real positions, counted from 0.

The third line printed, column 11 -> line 0, column 16, is the n in t(n): it came from price on the first line of cart.js. The fourth segment has a negative change, -14: it steps back from column 16 to column 2, on the next line.

To find where a generated position came from, a tool takes that line's segments and picks the last one that starts at or before the column. Everything up to the next segment belongs to it.

Index maps and debug IDs

A bundler that joins files can join their maps too, without decoding them. An index map has sections instead of mappings. Each section has an offset, where its code starts in the generated file, and a whole map.

const indexMap = {
  version: 3,
  sections: [
    { offset: { line: 0, column: 0 }, map: { version: 3, sources: ["cart.js"], names: [], mappings: "AAAA" } },
    { offset: { line: 40, column: 0 }, map: { version: 3, sources: ["shop.js"], names: [], mappings: "AAAA;AACA" } },
  ],
};

function findSection(line) {
  let found = null;
  for (const section of indexMap.sections) if (section.offset.line <= line) found = section;
  return found;
}

const section = findSection(41);
console.log(section.map.sources[0], "line " + (41 - section.offset.line) + " of its map");

Lines 4 and 5 are two sections: cart.js from line 0 and shop.js from line 40. Lines 9 to 13 pick the last section that starts at or before a line. Line 16 prints shop.js line 1 of its map: line 41 minus the offset 40.

The second problem is finding the right map at all. A stack trace names a URL, but the same URL may hold many builds over time. A debug ID fixes that: the generated file and its map carry the same unique ID.

function t(n){return n*1.2}
//# debugId=85314830-023f-4cf1-a267-535f4e37bb17
//# sourceMappingURL=cart.min.js.map

{
  "version": 3,
  "file": "cart.min.js",
  "debugId": "85314830-023f-4cf1-a267-535f4e37bb17",
  "sources": ["cart.js"],
  "names": ["addTax", "price"],
  "mappings": "AAAA,SAASA,EAAOC,GACd,OAAOA"
}

Line 2 of the file and line 4 of the map hold the same UUID. An error tracker that stores maps by debug ID can always find the map for the exact build that crashed. The debug ID comment goes above the sourceMappingURL line.

Debug IDs are still a proposal. Read each row of the table as: "this proposal is at this stage, and does this."

Symbolicating production stack traces

In production, errors arrive with positions in the minified code. Symbolicating turns each one back into your file, line, column and names. The one catch: stack traces count from 1, and maps from 0.

const sources = ["cart.js"];
const names = ["addTax", "price"];
// [generatedColumn, sourceIndex, originalLine, originalColumn, nameIndex], decoded from the map.
const segments = [[0, 0, 0, 0], [9, 0, 0, 9, 0], [11, 0, 0, 16, 1], [14, 0, 1, 2], [21, 0, 1, 9, 1]];

function symbolicate(frame) {
  const [, line, column] = frame.match(/:(\d+):(\d+)\)$/);
  if (line !== "1") return "no mapping";
  const generatedColumn = Number(column) - 1;
  let found = null;
  for (const segment of segments) if (segment[0] <= generatedColumn) found = segment;
  const name = found.length === 5 ? " (" + names[found[4]] + ")" : "";
  return sources[found[1]] + ":" + (found[2] + 1) + ":" + (found[3] + 1) + name;
}

console.log(symbolicate("at t (https://shop.example/cart.min.js:1:22)"));
console.log(symbolicate("at t (https://shop.example/cart.min.js:1:15)"));

Line 4 holds the decoded segments from the last section. Line 7 reads the line and column from the end of the frame. Line 9 takes 1 off the column, and line 11 finds the segment. Line 13 adds 1 back to the line and column.

Line 16 prints cart.js:2:10 (price): column 22 of the minified file is the n in n*1.2. Line 17 prints cart.js:2:3, the return.

Node.js can do this for its own stack traces. Here is a file that throws, minified, with its map next to it:

node --enable-source-maps cart.min.js

Error: price must be a number
    at addTax (/app/cart.js:3:11)
    at Object.<anonymous> (/app/cart.js:7:1)

Error: price must be a number
    at t (/app/cart.min.js:1:43)
    at Object.<anonymous> (/app/cart.min.js:1:92)

Without the map, the error points at column 43 of one long line, in a function called t. With --enable-source-maps, Node.js reads the map and points at cart.js line 3, inside addTax, using the names field. The stack trace API lesson shows how stack traces are built.

Explore a real map

Click any underlined piece of the minified code. The playground decodes its segment and highlights the code it came from.

1function addTax(price, rate) {
2  const total = price * (1 + rate);
3  return Math.round(total * 100) / 100;
4}
5console.log(addTax(10, 0.2));

Try o twice: the first is total where it is declared, the second where it is used. Both point to the same name.

Practical advice for real projects:

• Make maps in production builds too, so errors from users can be symbolicated.
• If you don't want to publish your code, upload maps to your error tracker instead of serving them, and leave out the sourceMappingURL comment.
• Keep each map with the exact build it came from; debug IDs make that automatic.
• Use ignoreList for library code, so debuggers step over it.

Common mix-ups

Most mix-ups come from forgetting that a map is only read by tools, and how it counts.

• "Source maps change how my code runs." No. The browser runs the generated code; only tools read the map.
• "Stack traces and maps count the same way." No. Stack traces count from 1, maps from 0.
• "Each segment stores a full position." No. Each number is a change from the segment before.
• "Every character has its own mapping." No. A segment covers everything up to the next one.
• "Without sourcesContent, the map is useless." No. Tools can fetch the files from sources; sourcesContent saves that step.

The table below puts three of these side by side. Read each row as: "people often think this, but this is true."

Practice exercises

Each exercise works on the numbers a map is made of. Guess first, then run it.

const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
const digits = ["C", "D"].map((char) => chars.indexOf(char));
console.log(digits.map((digit) => (digit & 1 ? -(digit >> 1) : digit >> 1)).join(" "));

const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
const digits = ["C", "D"].map((char) => chars.indexOf(char));
console.log(digits.map((digit) => (digit & 1 ? -(digit >> 1) : digit >> 1)).join(" "));

const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";

function encode(value) {
  let vlq = value < 0 ? (-value << 1) | 1 : value << 1;
  let out = "";
  do {
    let digit = vlq & 31;
    vlq >>>= 5;
    if (vlq > 0) digit |= 32;
    out += chars[digit];
  } while (vlq > 0);
  return out;
}

console.log(encode(16));

const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";

function encode(value) {
  let vlq = value < 0 ? (-value << 1) | 1 : value << 1;
  let out = "";
  do {
    let digit = vlq & 31;
    vlq >>>= 5;
    if (vlq > 0) digit |= 32;
    out += chars[digit];
  } while (vlq > 0);
  return out;
}

console.log(encode(16));

const mappings = "AAAA,EAAE;;AACA";
const lines = mappings.split(";");
const segments = lines.flatMap((line) => (line ? line.split(",") : []));
console.log(lines.length, segments.length);

const mappings = "AAAA,EAAE;;AACA";
const lines = mappings.split(";");
const segments = lines.flatMap((line) => (line ? line.split(",") : []));
console.log(lines.length, segments.length);

const segments = [[0, 0, 0, 0], [9, 0, 0, 9], [14, 0, 1, 2]];

function original(column) {
  let found = null;
  for (const segment of segments) if (segment[0] <= column) found = segment;
  return "line " + (found[2] + 1) + ", column " + (found[3] + 1);
}

// The stack trace says column 14. Stack traces count columns from 1.
console.log(original(14));

const segments = [[0, 0, 0, 0], [9, 0, 0, 9], [14, 0, 1, 2]];

function original(column) {
  let found = null;
  for (const segment of segments) if (segment[0] <= column) found = segment;
  return "line " + (found[2] + 1) + ", column " + (found[3] + 1);
}

// The stack trace says column 14. Stack traces count columns from 1.
console.log(original(14 - 1));

const relative = [[0, 0, 0, 0], [4, 0, 1, 2], [6, 0, 0, -1]];
const absolute = [];
for (const fields of relative) {
  absolute.push(fields);
}
console.log(absolute.map((fields) => fields.join(",")).join(" | "));

const relative = [[0, 0, 0, 0], [4, 0, 1, 2], [6, 0, 0, -1]];
const absolute = [];
let total = [0, 0, 0, 0];
for (const fields of relative) {
  total = total.map((value, index) => value + fields[index]);
  absolute.push(total);
}
console.log(absolute.map((fields) => fields.join(",")).join(" | "));

const sections = [
  { offset: { line: 0 }, file: "vendor.js" },
  { offset: { line: 120 }, file: "app.js" },
];

function locate(line) {
  let found = null;
  for (const section of sections) if (section.offset.line <= line) found = section;
  return found.file + " line " + line;
}

console.log(locate(125));

const sections = [
  { offset: { line: 0 }, file: "vendor.js" },
  { offset: { line: 120 }, file: "app.js" },
];

function locate(line) {
  let found = null;
  for (const section of sections) if (section.offset.line <= line) found = section;
  return found.file + " line " + (line - found.offset.line);
}

console.log(locate(125));

Check your understanding

For each question, ask whether a number is a change or a total, and whether it counts from 0 or from 1. Each answer explains why it's right or wrong.

Key takeaways

A source map is a compact table from generated positions to original ones.

• A map is JSON: sources, sourcesContent, names, and the mappings string.
• Base64 VLQ stores each number in letters of 6 bits: 5 data bits and a "more" bit, with the sign in the lowest bit.
• ; separates generated lines, , separates segments, and every number is a change.
• Index maps join maps by offset; debug IDs tie a file to its exact map.
• Stack traces count from 1 and maps from 0: take 1 off, look up, add 1 back.

Coming next: How minifiers work. They make the small, renamed code that source maps lead back from.