Source Map Decoder

Production JavaScript is minified: names are shortened, lines are joined and a whole application can live on one line of a file. When an error comes from such a file, the stack trace says only line 1, column 8,421. A source map is the file that records how each position in the generated code relates to the original source, and with it a trace can be turned back into names and lines a person recognises.

What is inside a source map

A source map is a JSON file. Its fields include version (3), file (the generated file), sources (the list of original files), names (identifiers that were renamed), sourcesContent (optionally the original code) and mappings. The mappings string is the compact part. Generated lines are separated by semicolons and segments within a line by commas. Each segment is up to five numbers in Base64 VLQ form: the column in the generated line, the index of the source, the original line, the original column and optionally an index into names.

Decoding the mappings

Variable-length quantities store small numbers in few characters. Each Base64 character carries five bits of value and a continuation bit, and the lowest bit of the result is the sign. All numbers except the generated column are deltas from the previous segment, and the generated column resets with every line. The decoder in the page expands the whole string into a table of segments and reports how many there are, which is a quick sanity check for a map that may be damaged.

Looking up a position

For a position in the generated file, the lookup finds the last segment on that line that starts at or before the column. That segment tells you the source file, line and column, and the name if there is one. Stack traces count lines and columns from 1 while the map counts from 0, so the page subtracts one for you. Paste the trace, and every frame is resolved; you can also type a single line and column into the lookup box.

Stack formats

Chrome and Node print frames as “at fn (https://example.com/app.min.js:1:32)”. Firefox and Safari print “fn@https://example.com/app.min.js:1:32”. The page reads both and resolves each frame against the map you pasted, so use a map that matches the file in the trace; frames from other scripts will map to wrong places or to nothing. A frame with no mapping is shown as “no mapping at this position”.

A worked example

The Sample button loads a small map for app.min.js with one source, src/math.js, two names, eight segments and the source included. The trace has two frames. The first frame, d at 1:32, resolves to src/math.js:2:22, which is the new Error call on line 2, and the original line “if (b === 0) throw new Error(‘Divide by zero’);” is displayed. The second, r at 1:84, resolves to src/math.js:7:3, the line return divide(10, 0);. The position 1:17 points at 2:3, the start of the if statement, and 1:1 maps to 1:8 with the name divide.

Limits

Only a single, plain version 3 map is read. Index maps with sections, maps in other versions and maps embedded as data URLs need separate handling. The page can resolve a position only as precisely as the map allows; minifiers may map a whole expression to one point. The map must come from the same build as the file in the trace, and the page never downloads anything, so you supply both texts yourself.

Related tools

• Code Minifier shows how code shrinks and why maps are needed.
• Diff Checker compares source versions once you have found the line.
• WebAssembly Inspector examines another kind of compiled web code.
• JSON Formatter makes a map file readable.