What Is a Source Map? Debugging Minified Code
A source map is a JSON file that maps positions in transformed, minified output back to the exact lines and columns of your original source.
Production JavaScript is transpiled, bundled, and minified until it barely resembles what you wrote. When an error fires, the stack trace points into that mangled output, which is useless for debugging. A source map restores the connection, letting browser dev tools and error trackers show your real source. How and where you generate and upload maps is a CI decision.
What a source map contains
A source map is a JSON document with the original file names, the original source content (optionally), and a compact set of mappings from each generated position to its source position. The build tool emits it alongside the output file.
How the browser uses it
A comment at the end of the output file points to the map. When dev tools are open, the browser fetches the map and displays original source in the debugger and in stack traces, even though the running code is minified.
The privacy trade-off
- Public maps make production code easy to read and reverse-engineer.
- Many teams upload maps to an error tracker instead of serving them publicly.
- Hidden source maps emit the file without the public reference comment.
Source maps and error tracking
Tools like Sentry symbolicate minified stack traces using uploaded maps. The pipeline builds with maps, uploads them to the error service, and then deploys without serving them to users, so traces stay readable without leaking source.
Source maps in CI/CD
Generating maps adds build time and output size, so production builds often emit them as separate artifacts that are uploaded and then excluded from the deploy. A CI step uploads the maps tied to the build commit so errors map back to the exact release.
Key takeaways
- A source map maps minified output back to original source positions.
- Public maps expose source; many teams upload them to an error tracker instead.
- CI typically generates maps, uploads them per release, then keeps them out of the deploy.