The Debugging Gap: Source Maps

The "Minified" Mess

To make websites load faster, production JavaScript goes through a build process that applies two transformations:

1. Minification: Removes whitespace, comments, and renames variables from descriptive names (calculateShoppingCartTotal) to single characters (a). A 500KB readable file might become 80KB.
2. Bundling: Combines dozens of separate module files into one or a few files to reduce the number of network requests.

The result is a file that browsers love but humans cannot read. When an error occurs in production, your monitoring tool reports something like:

TypeError: Cannot read properties of undefined (reading 'price')
    at app.min.js:1:47832

Line 1, character 47,832 of a minified file. This is completely useless for debugging.

Source Maps: The Rosetta Stone

A Source Map is a separate JSON file (typically named app.min.js.map) generated during the build process alongside the minified output. It contains a complete mapping from every position in the minified file back to the exact file, line, and column in your original source code.

When your browser's DevTools or your error monitoring service (like Sentry) has access to source maps, it transparently translates minified stack traces back into readable originals:

TypeError: Cannot read properties of undefined (reading 'price')
    at calculateShoppingCartTotal (src/cart/utils.ts:142:18)
    at CartSummary.render (src/components/CartSummary.tsx:67:5)

Now you know exactly where to look.

Security consideration: Source maps expose your original source code. You have two options:
- Upload to your error monitoring service only (e.g., Sentry's artifact upload). The maps are never served publicly, but Sentry uses them server-side to symbolicate stack traces before displaying them.
- Serve publicly (simpler, but exposes your source). Only acceptable if your code isn't proprietary.

Most production setups use the first approach: build with source maps, upload them to your error monitoring tool during CI/CD, then either delete them or configure your web server to block public access to .map files.