The mapping problem
Browsers run minified, transpiled, bundled code that looks nothing like what you wrote. A stack trace pointing at line 1 column 40000 of a single bundle is useless. A source map is a separate file that maps positions in the generated output back to positions in your original sources.
- It records which output range came from which source line.
- The browser loads it to display original files in dev tools.
- Stack traces then point at your real file names and lines.
Generation and use
Build tools emit a source map alongside the bundle and add a comment linking the two. When dev tools open the map, breakpoints, the debugger, and error stacks all show original code even though minified code is what runs.
- Inline or external: embedded in the file or shipped separately.
- Privacy: keep production maps off public servers or behind auth.
- Errors: error tracking tools use maps to symbolicate traces.
Without source maps, debugging production issues means reading machine generated soup. With them, you debug the code you actually authored. The cost is generating and storing the maps, which is small next to the time they save.
Key idea
A source map links generated bundle positions back to original source lines so debuggers and stack traces show real code.