The file served to the browser is no longer the one you wrote: it went through a Transpilation step, then assembly and compression. The day an error comes back, it names line 1 column 48213 of an unreadable file.
A source map restores the link between those two worlds.
Definition
A source map is a file pairing every position in the generated code with the matching position in the original source. Developer tools load it automatically and show your original files instead of the file actually running.
// Last line of the produced file
//# sourceMappingURL=bundle.js.map
// bundle.js.map, simplified
{
"version": 3,
"file": "bundle.js",
"sources": ["../src/cart.js", "../src/utils.js"],
"names": ["cartTotal", "discount"],
"mappings": "AAAA,SAASA,YAAT,CAAsBC,MAAtB..."
}The mappings field holds the correspondences in a compact format, unreadable to the naked eye but highly compressible. An optional sourcesContent field also embeds the text of the original files, which makes the map self-contained.
How to turn it on
Every tool exposes a setting: build.sourcemap in Vite, devtool in Webpack, a command line option for a compiler. The choice trades precision against generation speed.
In development, an approximate but fast map is plenty. For production, a complete map is worth more, since it will rarely be consulted, but always at a moment when every clue counts.
An error tracking service will accept the maps separately, at deployment time. The stack traces it reports become readable for the team, without the files being publicly reachable.
Should they be published?
A source map shipped online exposes your original source, comments included, to anyone opening the developer tools. That is not a vulnerability in itself, since the running code, even after Minification, was already available, but it is a real difference in comfort for a curious reader.
The practical rule is simple: always generate the maps, then decide whether to serve them or to send them only to your error tracking tool. What you must never do is skip generating them: the first production error will then be impossible to locate.
Frequently asked questions
Do source maps slow the site down?
Not for visitors: the browser downloads the map only when developer tools are open. The cost lands on the build, which takes longer, and on server storage.
Why is my stack trace still unreadable?
First check that the map file really is reachable at the address named by the final comment, a 404 being the most common case. Then check that the map matches the deployed version: a file regenerated afterwards no longer points at the right lines.
Do they work for CSS too?
Yes, and the principle is identical. A stylesheet compiled from a preprocessor or generated by a tool points back to the original file in the inspector, which saves you from hunting for the place a rule was actually written.