Source Maps

A JavaScript pipeline destroys source correspondence exactly the way a compiler backend does. TypeScript erases types and lowers syntax. Babel rewrites modern constructs into older ones. A bundler concatenates hundreds of modules into one file and rewrites their imports. A minifier renames every local variable to one letter, removes whitespace, inlines functions and collapses the result onto a handful of extremely long lines. What executes bears no textual resemblance to what anybody wrote.

The answer is structurally identical to [[debug-information]]: emit a mapping alongside the output. What differs is the container and the coordinate system. Instead of DWARF sections keyed by machine address, a JSON file keyed by generated line and column; instead of a state-machine program, a delta-encoded string; instead of a debugger reading ELF, a browser devtools panel reading a //# sourceMappingURL= comment at the end of the file.

It is worth holding the two together, because the shared structure is the lesson. Both exist because a stage discarded information a human will need later. Both are optional, generated only on request, and both are useless if the artifact that consumes them cannot find them. Both degrade under aggressive transformation. And both have the property that a *chain* of stages requires each stage to compose its mapping with the previous one — which DWARF gets for free because there is one compiler, and which JavaScript does not, because there are four tools from four vendors.

The mappings field is where the format earns its size, and understanding it takes about five minutes and removes all the mystery from a corrupt map.

The string is split by ; into groups, one per generated line — so the count of semicolons tells you how many lines the output has. Within a group, , separates segments, each describing one position in that line. A segment is one, four or five numbers: generated column; index into sources; original line; original column; and optionally an index into names. A one-field segment means "generated code here maps to nothing", which is how you mark output the tools invented.

Every number is relative to the previous one — that is the compression. Generated column resets at each new line; source index, original line and original column carry over across lines and continue accumulating. Then each number is encoded as Base64 VLQ: split into six-bit groups, the low bit of the first group is the sign, the top bit of each group says "another group follows", and the six-bit values are indexed into the standard Base64 alphabet. So a delta of zero is A, one is C, minus one is D.

Two practical consequences fall out of the delta encoding. First, the map is a *stream* — corrupt or drop one segment and every subsequent position in the file is shifted, which is why a broken map is usually broken everywhere rather than in one place. Second, the encoding is why maps are still large despite being deltas: a minified bundle has a segment for essentially every token, and the .map file is routinely bigger than the code it describes.

The single most common source-map failure in practice is not a malformed map. It is a correct map that points at the wrong thing, because a chain of tools did not compose.

Consider a realistic pipeline: TypeScript compiles src/app.ts to build/app.js and emits app.js.map pointing at the .ts. A bundler concatenates build/*.js into bundle.js and emits bundle.js.map. A minifier turns that into bundle.min.js and emits bundle.min.js.map. If each stage only maps to *its own input*, the final map points at bundle.js — an intermediate artifact that exists on the build machine and nowhere else. The browser dutifully shows you a file it cannot fetch, or shows you bundled-but-unminified JavaScript that is not your source.

The correct behaviour is that each stage reads the incoming map and emits a map composed through it, so the final map points all the way back to src/app.ts. Modern tools do this by default when they can find the input map, and the failure modes are all about *finding* it: an intermediate step that strips the sourceMappingURL comment, a build that pipes through stdout and loses the file, a tool configured with an input map path that no longer exists, a copy step that moves the JavaScript and not the .map.

The diagnosis is mechanical, and worth knowing because it takes two minutes. Open the final .map and read its sources array. If it lists your original files, composition worked. If it lists an intermediate bundle, you have found the stage that dropped the chain — it is the one whose output those names correspond to.

Source maps in production are the same decision as shipping debug information, with the same right answer and a sharper privacy edge. A minified stack trace from a real user is a list of positions in bundle.min.js at line 1, column 84213 — useless without a map. So error-reporting services want the map, and the standard arrangement mirrors [[symbolication]] exactly: generate the map, upload it to the error reporter keyed by a release identifier, and do *not* serve it publicly.

The privacy edge is that a source map with sourcesContent embeds your original source, comments included. Serving it from the public origin publishes your codebase. Serving the .map but not the sourcesContent publishes your file and directory names. Both are choices rather than accidents, and both are made by default by a build configured without thinking about it. The options are: do not emit the sourceMappingURL comment in production and upload the map out of band; or serve the map from an authenticated path; or accept the disclosure deliberately, which many open-source projects reasonably do.

Node has a directly useful counterpart worth knowing: node --enable-source-maps makes the runtime apply source maps to stack traces itself, so an unhandled exception in a compiled TypeScript service prints .ts positions. It has been available since Node 12.12 and is off by default for the cost of loading and applying the maps.