Blog Read minified stack traces with source maps
Read minified stack traces with source maps
TL;DR A source map maps minified code back to your original source. Generate them in your build, and DevTools will show real file names and line numbers in stack traces. For server-side or logged errors, use the map to translate a minified location back to the source manually.
You ship a bug, and the error report reads like a ransom note: main.abc123.js:1:40122. Minification squeezed your code into a couple of enormous lines, so the trace is technically correct and completely unhelpful. Source maps translate it back into something you can read.
What a source map does
A source map is a companion file that records how the minified, bundled output relates to your original source. Given a position in the minified file, it tells you the real file, line, and column. It is the dictionary between what shipped and what you wrote.
Generate them in your build
Most build tools produce source maps with a flag or a config option. Turn it on for your production build so a .map file is emitted alongside each bundle. That is the raw material for everything else.
Let DevTools do the work
If the browser can find the source map, it uses it automatically. Open the error in the console, and the stack trace shows your original file names and line numbers instead of the minified ones. You can even step through your real source in the debugger, despite the shipped code being minified.
For this to work in production, the map has to be reachable, either served next to the bundle or provided to your tooling.
For server-side or logged errors
When the error is logged rather than opened in a browser, DevTools cannot help. Feed the minified position and the source map into a source-map tool and it returns the original location. This is exactly what error-tracking services do: you upload your maps to them, and they show you readable traces for every reported error automatically.
The privacy angle
Source maps expose your original source, which you may not want publicly downloadable. The common answer is to generate them, upload them to your error tracker, and not serve them from the site. You keep readable production traces without publishing your code.
Why bother
Without source maps, a production stack trace tells you an error happened and nothing about where. With them, it points at the exact line in the exact file you wrote. That is the difference between guessing and fixing. Turn them on before you need them, because the moment you need them is always after something has already broken.
FAQ
What is a source map?
It is a file that records how minified, bundled output relates to your original source. With it, a tool can take a position in the minified file and tell you the real file, line, and column it came from, so a stack trace becomes readable again.
Should I ship source maps to production?
You need them available to translate production errors, but you may not want them publicly downloadable if the source is sensitive. A common approach is to upload them to your error-tracking service rather than serve them from the site.
Why is my stack trace all on line 1?
Because minification collapses your code into very few, very long lines. The trace is accurate for the minified file but useless to a human. A source map is what turns that line 1, column 40000 back into a real location in your code.