Source map
A source map is a JSON file that maps compiled or minified JavaScript (or CSS) back to its original source — typically including the full original file paths and their complete contents.
In detail
When a build tool like webpack, Vite, Rollup, esbuild or SWC compiles a project, the output is nothing like what the developer wrote. Variable names are mangled, whitespace is stripped, modules are concatenated, tree-shaking removes unused code, and everything is packed into a handful of minified `*.js` files. The source map (the file ending in `.map`) is the inverse of that transformation: it records which byte in the minified output came from which line of which source file, and — if the bundler is configured to include them — the full contents of every original source file alongside that mapping.
Structurally, a source map is a JSON document with a small, stable schema. The `version` field (currently 3) advertises the spec version. The `sources` array lists every source file by its original path. The `sourcesContent` array, when present, holds the literal text of each source at the same index. The `mappings` field is a VLQ-encoded base64 string that tells a debugger exactly which generated byte came from which original position — it's the heavyweight part and is only relevant if you're building a stack-trace de-minifier. For simply recovering source, only `sources` and `sourcesContent` matter.
Production error-tracking tools like Sentry, Datadog and Bugsnag use source maps to de-minify stack traces. Browsers use them to present readable code in DevTools (try enabling 'Source Maps' in Chrome's Sources panel — error stacks become readable). And when they're exposed publicly, they become a complete copy of the site's original source, ready to be reconstructed into a browsable project tree.
History and origins
The Source Map spec v3 was drafted around 2011-2012 by engineers at Google, Mozilla and other browser vendors, aiming to standardize what had been ad-hoc per-tool conventions. Before v3 each build tool had its own source-mapping approach, which made cross-browser debugging inconsistent. The spec has been exceptionally stable since — v3 is still the current version, and every modern build tool produces compliant maps.
Terminology variants
- Source map
- Sourcemap (one word — common in tool output and file extensions)
- Source Map v3 (the specification)
- .map file (file extension)
Common misconceptions
Source maps are only for debugging.
They're for debugging in intent, but their `sourcesContent` field makes them a complete copy of the source. When served publicly, they effectively ship the team's `src/` folder alongside the bundle.
You need to disable source maps to protect production source.
The safer option is to emit maps and upload them privately to your error tracker (Sentry `sentry-cli sourcemaps upload` workflow) rather than serving them publicly. That keeps error de-minification working without exposing the source.
Source maps include server-side secrets.
They include client-side source — frontend code that the server already sent to the browser in minified form. Backend secrets, API keys held on the server, database credentials — none of that is in a source map.
Reading source maps is a grey-area activity.
You're reading a file your browser already requested. The resulting code is copyrighted by its authors — study it, don't rehost it — but access itself is unremarkable.
Examples
In practice
If you're debugging a production error, you point your error tracker at the map. If you're studying a production frontend, you fetch the map and reconstruct the source tree. If you're shipping a new version of your own app, the question is always 'do we serve the map publicly or upload it privately?' — and most teams end up serving it publicly because the friction of the upload step isn't worth the (small, reputational-only) security benefit.
FAQ
Is shipping sourcemaps to production a security risk?
It depends on threat model. Sourcemaps reveal the shape of the source — functions, constants, comments, sometimes commented-out code. They don't reveal server secrets, API keys held on the backend, or unauthenticated data. For most public web apps the cost is reputational/IP, not security. Teams serious about hiding source should either disable sourcemaps in production or upload them to their error-tracking provider separately rather than serving them publicly.
Can I rebuild the original TypeScript from a JavaScript sourcemap?
Yes, if the bundler included the TypeScript files in `sourcesContent`. Most modern build tools (Vite, Next.js SWC, Webpack with ts-loader) include them by default.
Do CSS bundles have source maps?
Yes. Tailwind, Sass, PostCSS and similar all emit `.css.map` files when configured. The schema is the same as JS source maps; `sources[]` lists the original SCSS/PostCSS files, `sourcesContent[]` has their text.
How big can a source map get?
Production sourcemaps routinely range from 5 MB to 50 MB per bundle. A full site with a dozen bundles can accumulate several hundred MB. That's one reason Sourcemap Explorer requires the `unlimitedStorage` permission — the default 5 MB browser quota isn't enough.
Related how-to guides
Sourcemap Explorer turns these concepts into a workflow.
Free browser extension, no sign-up, no backend.