Source maps in production: readable errors, private code
Short answer: The JavaScript your site ships to browsers is minified, so error reports from real users point at line 1, column 48,213 of a file nobody can read. Source maps translate those positions back to your original code. Generate them for production builds, upload them to your error-tracking tool, and usually do not publish them on your website: a "hidden" source map gives your error tool readable stack traces without handing the public a neat copy of your source code.
The problem with production error reports
Modern front-end builds bundle, minify and sometimes transpile your code. That makes files small and fast, which is right for customers, but it also turns errors into gibberish. A report from your error tracker might say a TypeError happened in a function called "e" in main.4f3a.js. Without help, a developer has to guess which of hundreds of components failed.
For a business, that slows down fixing exactly the bugs that matter: the ones real customers hit on real devices, which often never appear in testing.
What a source map is
A source map is a separate file, usually ending in .map, that records how each position in the built file corresponds to a position in your original source files. Tools that understand source maps, including browser developer tools and error-tracking services, use it to show the original file name, line and function.
There are two ways a browser learns where a map lives. MDN's documentation on the SourceMap HTTP header explains that the header gives the location of a source map, and that it takes precedence over a sourceMappingURL comment at the end of the file if both are present. If neither is there, the browser has no reference to the map, but other tools can still use it if you give it to them.
Public or hidden?
When a source map is publicly reachable and referenced, anyone opening developer tools on your site sees your original, readable code, often including comments and internal names. That is not a disaster for most sites, since browser code is never truly secret, but it does make it easier to study your app, and it can expose things that should never have been in front-end code in the first place, such as API keys or internal URLs.
Build tools let you choose. Webpack's documentation on its devtool option lists many variants. Two are especially relevant:
- hidden-source-map produces full source maps but adds no reference to them in the bundle. Webpack's docs describe it as a possible choice when using source maps only for error reporting purposes.
- nosources-source-map variants map positions but do not include the source code itself, so stack traces show file names and line numbers without exposing the code.
Other bundlers such as Vite, Rollup and esbuild offer equivalent settings, typically a "hidden" option.
Uploading maps to your error tracker
The usual production setup is:
- Build with hidden source maps.
- Upload the .map files to your error-tracking service as part of the deploy.
- Delete the .map files from the build output before it goes to your web server or CDN, or block them from being served.
Sentry's documentation, for example, covers uploading source maps for bundlers including webpack, Rollup, Vite and esbuild. It explains that by default Sentry links source maps to your code by injecting Debug IDs into the build output, and that other association methods exist that do not modify the build. Other error trackers have similar upload steps or command-line tools.
Getting the details right
- Match the release. Maps only work for the exact build they were generated from. Tie each upload to a release or version, and make sure the error tracker knows which release a report came from.
- Automate it. Uploading by hand is forgotten within a month. Add it to your continuous integration or deploy script.
- Check it works. After setting up, trigger a deliberate test error in production and confirm the stack trace shows original file names and lines.
- Handle third-party code. Errors in scripts you did not build will still appear minified; filter or ignore them if they are noise.
- Do not rely on obscurity. Hidden maps make code less convenient to read, not secret. Keep secrets on the server.
Who should be able to see the mapped errors
Once your error tracker can show original code, its dashboard becomes a place where your source is readable, so treat access to it like access to your code repository. Give accounts to the developers and support leads who need them, remove access when people leave, and avoid pasting full stack traces with customer details into public tickets or chat channels. Many trackers also let you scrub personal data such as email addresses from reports before they are stored, which is worth switching on at the same time as source maps.
A worked example
Take a hypothetical Manchester property-listings site built as a single-page app. Its error tracker showed hundreds of reports each week, all pointing at the same minified bundle, so the team mostly ignored them. Meanwhile some users on older phones could not submit the viewing request form.
The developers switched the build to hidden source maps, added an upload step to the deploy pipeline linked to the release version, and removed .map files from the files sent to the CDN. Within a day, the stack traces pointed to a date-picker component calling a browser method older phones lacked. A fix went out that afternoon, and the error reports became something the team read rather than skipped.
FAQ
Do source maps slow down my site?
No, not for normal visitors. Browsers only download maps when developer tools are open and a reference exists. Hidden maps are not downloaded by visitors at all.
Is it bad to have public source maps?
Not necessarily. Some open-source projects publish them deliberately. For commercial apps, keeping them private is a sensible default.
Do I need source maps for server-side code?
They help there too if you transpile or bundle server code, for example TypeScript. Most server runtimes and error trackers support them.
If your error reports are unreadable and real-user bugs go unfixed, tell us how your front end is built and deployed.