Source maps, and why your stack trace still lies

Everything that makes JavaScript fast to download makes it impossible to debug. Source maps are the file that undoes that, and they are the most misunderstood artefact in a modern build.

What a source map actually is

A source map is a JSON file that says where each piece of the generated code came from. Nothing more. It contains no executable code and the browser does nothing with it until you open devtools.

The shape has been stable since version 3 of the format, and it is now a TC39 standard rather than a shared Google document. The fields you meet:

sourcesContent is the field with consequences. With it, the map is self-contained and devtools can show your original code without fetching anything else. It is also, literally, your source code in a JSON string. That single field is what makes "should we ship source maps" a real question rather than an obvious yes.

ignoreList is newer and underused. It marks entries in sources as framework or dependency code, and Chrome devtools then hides them from stack traces and steps over them in the debugger. Bundlers emit it for node_modules automatically, and it makes a React stack trace considerably shorter.

Inside the mappings field

Open a .map file and one field dominates: a long string that looks like line noise.

"mappings": "AAAA,SAASA,EAAEC,GAAG,OAAOA,EAAI,EAAE,CAAC"

It is a list of positions, encoded so it does not take megabytes. Semicolons separate lines of the generated file; commas separate segments within a line. Each segment carries up to five numbers: the column in the generated file, an index into sources, the original line, the original column, and optionally an index into names.

Two tricks keep it small. Every number is a delta from the previous segment rather than an absolute value, so the digits stay tiny. And each delta is base64 VLQ encoded, a variable-length format where the low bit carries the sign, five bits carry data and the top bit says whether another group follows. A minified bundle needs a segment for roughly every token, and this is what turns tens of millions of digits into a few hundred kilobytes.

You will never write this by hand, but knowing the structure explains two things you will meet. A "cheap" devtool setting omits column data, which is fine for readable source and useless for minified code where an entire module lives on line 1. And the mapping is positional only: it points at a location in a file, so if the file it points into is not the file you built, the result is a confident answer to the wrong question. That is the failure mode in the stale maps section below.

How the browser finds the map

Two mechanisms, and the second one is nearly forgotten.

The usual one is a comment on the last line of the JavaScript file:

//# sourceMappingURL=app.4f3a9c1e.js.map

It must be the last line, since anything after it is ignored. The older //@ form was replaced because it collided with IE's conditional compilation. For CSS the same comment uses /*# sourceMappingURL=... */.

The other is an HTTP response header, SourceMap: /maps/app.js.map, which attaches a map without touching the file at all. It is genuinely useful: you can serve maps to your own IP range or behind an authenticating proxy while everyone else gets a bundle with no hint that maps exist. Support has been in Chrome and Firefox devtools for years, and almost nobody uses it.

Third form: an inline map, where the whole JSON is base64 in a data URI appended to the file. Convenient in development, indefensible in production, since every visitor downloads a file several times bigger than the code. If you ever need to look inside one, decode the part after base64, with our base64 decoder and drop the result into the JSON formatter to see the fields laid out.

Should you ship them?

The objection is usually performance, and it is misplaced. A browser fetches a .map file only when devtools are open. For a normal visitor the entire cost is the length of the sourceMappingURL comment, which is under a hundred bytes.

The real question is disclosure. A map with sourcesContent is your source code, comments and all, served from your own CDN. Whether that matters depends on what the code is. A marketing site, no. A pricing engine or a client with licensing logic in it, quite possibly.

Worth being clear about a related confusion: minification is not protection. Names get shortened, whitespace disappears, and the logic is entirely intact and readable to anyone who wants it, which is the distinction we work through in minify, uglify, obfuscate. If your threat model requires the client code to be unreadable, source maps are not the thing standing in your way. If it does not, publishing maps is a gift to whoever is debugging your site at 2am, and that person is usually you.

Our own position: ship maps for anything public-facing, use hidden maps where the bundle is a product, and never let the decision be made accidentally by a default in a build config nobody has read.

Hidden maps and error trackers

The middle path is well supported. Generate the map, do not advertise it, upload it to the error tracker, and delete it from the deployed output:

• Vite: build.sourcemap: 'hidden'
• webpack: devtool: 'hidden-source-map'
• esbuild: --sourcemap=external
• Next.js: productionBrowserSourceMaps for public maps; the Sentry plugin handles the hidden case and the upload together

Then the tracker symbolicates on its side: your team reads Cart.tsx:112, the public gets app.js:1:48210, and nothing on the CDN reveals the source.

The part that fails in practice is matching a stack trace to the right map. Path-based matching breaks whenever a build directory changes or two deploys share a file name. Debug ids fix it properly: a unique identifier is injected into both the bundle and its map at build time, and the tracker matches on that identifier instead of guessing from a URL. Sentry's bundler plugins do this automatically now, and it removed most of the "unminified frames missing" tickets we used to see.

Why the line numbers are wrong

A map that points at the wrong place is worse than no map, because you trust it. Four causes, in the order we run into them:

• Version mismatch. The map was built in a different run than the bundle the user executed. A rebuild between deploy and upload is enough. Content hashes in file names plus debug ids fix this.
• Cached bundle, new map. The user is running yesterday's JavaScript out of the browser cache while the tracker holds today's map. Long-lived immutable caching for hashed files prevents it, which is the same argument as in HTTP caching without tears.
• A transform after the map was made. A CDN that re-minifies, an inline-script injector, an A/B testing proxy that rewrites the bundle. The map describes a file that no longer exists.
• Two-stage builds without map merging. TypeScript to JavaScript, then bundling, then minification. Each step must consume the previous map and emit a merged one. Tools handle this when configured correctly and silently produce a map to the intermediate file when not, which is why a stack trace occasionally points at compiled output rather than your .ts file.

If you want to check whether a map is even plausible before blaming the tracker: the file field should name the bundle you deployed, sources should list paths you recognise, and the number of semicolons in mappings should be close to the number of lines in the generated file. A map for a minified bundle usually has very few semicolons, because there are very few lines. Two, when the file has one line and a trailing newline, is normal rather than broken.

The bundler settings worth knowing

webpack's devtool has more than a dozen values and the naming is compositional rather than descriptive:

In practice: eval-cheap-module-source-map for development, source-map or hidden-source-map for production, nothing else. Vite defaults to maps on in development and off in production, so shipping them is an opt-in you have to write down.

A last note on the minifier itself. Terser and esbuild both emit maps for their own transformation, and both need the incoming map to chain correctly through a multi-step build. If you are checking what a given file looks like after minification, or comparing what two settings produce before wiring them into a pipeline, our JavaScript minifier runs Terser in your browser and shows the gzip size of the result; the uglifier is the same engine with top-level mangling enabled, which is the setting that makes a map indispensable rather than merely convenient. The specification is at tc39.es/source-map if you need the exact VLQ rules.

Source map questions