Source Maps Explained: How They Work and Why They Sometimes Leak Source Code

Most developers only think about source maps when DevTools magically shows the original TypeScript instead of unreadable bundled JavaScript.

That convenience hides an important fact:

A source map is not just “debug metadata.” It is a translation table between generated code and original source code.

And depending on how it is emitted, it can contain the original source itself.

That is why source maps sit at the intersection of:

• debugging
• build tooling
• browser DevTools
• error reporting systems like Sentry
• security and accidental code exposure

If you have ever wondered how a minified file can still produce readable stack traces, or how a published .map file can expose a package’s real TypeScript source, this is the mental model you want.

The Problem Source Maps Solve

In development, code usually looks like this:

• many small files
• readable variable names
• comments
• TypeScript or JSX
• line breaks that make stack traces useful

In production, code often looks very different:

• bundled into fewer files
• transpiled from TypeScript to JavaScript
• minified
• variable names shortened
• whitespace removed

For example, you might write this:

export function calculateTotal(price: number, taxRate: number) {
  const tax = price * taxRate;
  return price + tax;
}

But ship something closer to this:

export function c(t,r){return t+t*r}

That is good for performance and shipping, but terrible for debugging.

If production throws an error at column 23 of app.min.js, that position is almost meaningless to a human.

A source map fixes that by saying:

Position generated.js:1:23 corresponds to src/billing.ts:2:15.

That is the core idea.

What a Source Map Actually Is

A source map is usually a JSON file with a .map extension, such as:

• app.js.map
• vendor.min.js.map
• cli.js.map

Its job is to map locations in generated code back to locations in original files.

A typical source map contains fields like these:

{
  "version": 3,
  "file": "app.min.js",
  "sources": ["src/billing.ts"],
  "sourcesContent": [
    "export function calculateTotal(price: number, taxRate: number) {\n  const tax = price * taxRate;\n  return price + tax;\n}\n"
  ],
  "names": ["calculateTotal", "price", "taxRate", "tax"],
  "mappings": "AAAA,SAASA,eAAeC,KAAaC,OAAkB,CACrD,MAAMC,MAAMF,QAAQC,OACpB,OAAOD,QAAQE,GACjB"
}

The important fields are:

Two fields matter more than most people realize:

• sources
• sourcesContent

If sourcesContent is present, the source map may already contain the full original source code inline.

That is the part that surprises people.

How the Browser Finds a Source Map

Generated JavaScript often ends with a special comment:

//# sourceMappingURL=app.min.js.map

That comment tells tools where the map lives.

When browser DevTools sees that comment, it can fetch the map and use it to:

• display original files
• let you place breakpoints in original code
• rewrite stack traces
• step through TypeScript or JSX as if that were the runtime source

This is also why accidentally shipping a .map file publicly can be enough to expose a lot more than the minified bundle suggests.

There is also an inline form where the map is embedded directly into the JavaScript as a data URL, but external .map files are more common in production builds.

The Core Mental Model

A source map does not mean the runtime is executing your TypeScript.

The runtime still executes JavaScript.

The source map is only a lookup table that says:

• this generated line and column came from that original file
• this generated segment corresponds to that original symbol

So there are really two parallel worlds:

1. Generated code, which actually runs
2. Original code, which humans want to debug

The source map is the bridge between them.

How the Mapping Works Exactly

Source maps map positions, not just files.

They usually map:

• generated line
• generated column
• source file index
• original line
• original column
• optional name index

The mappings field stores these mappings in a compact encoded format.

The encoding uses three important ideas:

1. Semicolons separate generated lines
2. Commas separate segments on the same generated line
3. Each segment is Base64 VLQ-encoded and usually stores relative offsets

That sounds ugly because it is ugly. It was designed for machines, not humans.

The mappings Field in Plain English

Imagine the generated code is one minified line:

function c(t,r){return t+t*r}

Now imagine the original source is:

export function calculateTotal(price: number, taxRate: number) {
  const tax = price * taxRate;
  return price + tax;
}

The source map might record facts like:

• generated column 0 maps to src/billing.ts, line 1, column 0
• generated column 9 maps to the original function name
• generated column 11 maps to original parameter price
• generated column 13 maps to original parameter taxRate
• generated column 16 maps to original return

It does not need to record every single character. It records enough segments for tools to reconstruct the relationship between the generated file and the original source positions.

What a Segment Contains

After decoding, a segment can have up to five fields:

[generatedColumn, sourceIndex, originalLine, originalColumn, nameIndex]

In practice:

• generatedColumn says where this segment starts in the generated line
• sourceIndex points into the sources array
• originalLine is the original line number
• originalColumn is the original column number
• nameIndex points into the names array if a symbol name is attached

Not every segment has all five fields.

The shortest useful segment is often four fields, and the fifth is included when symbol name metadata is available.

Why the Values Are Relative

Source maps compress aggressively.

Instead of storing absolute values repeatedly, segments usually store deltas relative to the previous segment.

That means:

• if the next mapping stays in the same source file, the sourceIndex delta may be 0
• if the next original line is just one line later, the stored delta may be 1
• if the next generated column is nearby, that delta is small too

Small numbers compress well with Base64 VLQ.

That is why the mappings string looks cryptic while still staying fairly small.

What Base64 VLQ Is Doing

You do not need to memorize the bit layout, but you should know the purpose.

VLQ stands for Variable Length Quantity.

It is a way to encode integers compactly, especially when many of them are small.

The source map format then uses a Base64 character set to serialize those encoded integers into text.

So the mappings field is basically:

1. a sequence of relative numeric fields
2. VLQ-encoded
3. turned into Base64 characters
4. grouped into segments and lines

That is why a source map is both:

• compact enough to ship
• rich enough for debuggers to recover file, line, column, and symbol information

How DevTools Uses a Source Map

When you open DevTools and click what looks like an original .ts or .tsx file, DevTools is usually doing something like this internally:

1. load the generated JavaScript
2. discover the sourceMappingURL
3. fetch the .map file
4. decode sources, names, and mappings
5. build a translation index between generated and original positions
6. show you the original source, often from sourcesContent

Then when an exception happens at:

app.min.js:1:48192

DevTools can translate it into something like:

src/components/Checkout.tsx:87:14

That is the whole magic.

Source Maps Are Also Used Outside the Browser

Many developers associate source maps only with front-end apps, but they are also useful for:

• Node.js stack traces
• server-side bundling
• CLI tools
• error reporting services
• log processing pipelines

For example, if a TypeScript CLI is compiled into a bundled cli.js, a source map can still help turn runtime stack traces back into the original .ts or .tsx files.

That is one reason source maps show up in npm packages too, not just browser bundles.

Why Source Maps Sometimes Leak Real Source Code

This is the part that causes trouble.

A lot of people assume the .map file only contains coordinates.

That is not always true.

If the map includes sourcesContent, it may contain:

• original TypeScript or JSX
• comments
• internal file paths
• feature flags
• unused code paths removed from the final bundle
• symbol names that were shortened away in minified output

So if a private CLI or server-side package ships:

• dist/cli.js
• dist/cli.js.map

and that map includes embedded source content, anyone with access to the published package can potentially reconstruct much more of the original codebase than the minified bundle alone reveals.

That is how teams end up saying:

“We only published build artifacts.”

when in reality they also published a blueprint back to the original source.

Why This Happens in Practice

There are a few common causes:

1. Tooling defaults

A bundler or compiler may emit source maps automatically in production.

2. Source maps added for error monitoring

Teams want readable stack traces in Sentry or another telemetry platform, which is reasonable.

3. Publishing workflows are too broad

Instead of publishing only the intended artifacts, the package includes everything in dist/, including .map files.

4. People confuse “minified” with “safe”

Minification is not a security boundary. It only makes code less pleasant to read.

5. sourcesContent is enabled

This is the biggest difference between “a useful debugging map” and “a possible source leak.”

An Important Nuance: Not All Source Maps Are Equally Risky

There are several different deployment patterns:

Public source maps

These are accessible to users and browsers. Great for debugging public front-end apps, but they can expose more than expected.

Hidden source maps

These are generated for tooling and error reporting, but not linked from the served JavaScript with sourceMappingURL.

Private uploaded source maps

These are uploaded directly to a service like Sentry and never shipped publicly with the app or package.

If you want the debugging benefits without broadly publishing your original source, the last two patterns are usually the safer choice.

What Source Maps Can and Cannot Do

Source maps can:

• map generated code back to original files
• improve debugging
• recover symbol names when available
• let tools show original TypeScript, JSX, or multiple input files

Source maps cannot:

• make JavaScript secret
• protect proprietary front-end logic
• act as a real obfuscation barrier
• change what code is actually running

That distinction matters.

If code must stay private, do not rely on bundling or minification to protect it. If it runs on the client, the client ultimately gets executable code.

A Simple End-to-End Example

Here is the full lifecycle in one flow.

Step 1: You write original source

// src/math.ts
export function square(x: number) {
  return x * x;
}

Step 2: The bundler emits JavaScript

function s(n){return n*n}export{s as square};

Step 3: The bundler emits math.js.map

That map says, in effect:

• generated s came from original square
• generated parameter n came from original x
• generated return n*n came from return x * x

Step 4: The generated file references the map

//# sourceMappingURL=math.js.map

Step 5: A debugger or error reporter uses the map

When an error happens in the bundled file, the tool translates the generated location back into the original src/math.ts.

That is the entire system.

Practical Recommendations

If you are building libraries, web apps, or CLIs, the right approach is usually:

1. Decide whether source maps should be public, hidden, or private-only.
2. Audit whether sourcesContent is included.
3. Check what actually gets published to npm or deployed to production.
4. Verify your telemetry workflow separately from your public artifact workflow.
5. Treat .map files as review-worthy artifacts, not harmless leftovers.

For many teams, the safest setup is:

• generate source maps for error reporting
• upload them to your monitoring system
• avoid publishing them broadly if they expose source you did not intend to ship

Final Takeaway

Source maps are one of those pieces of tooling that feel invisible when they work and very visible when they go wrong.

They exist because production JavaScript is optimized for machines, while debugging is optimized for humans.

A source map is the bridge between those two worlds.

That bridge is incredibly useful:

• it gives you readable stack traces
• it lets DevTools show original TypeScript
• it makes modern bundling practical

But it can also expose far more context than people expect, especially when sourcesContent is included and .map files are published carelessly.

So the correct mental model is not:

“A source map is just a tiny debug file.”

It is closer to this:

“A source map is a compact, machine-readable reconstruction guide from generated code back to the original program.”

Once you see it that way, both the debugging value and the security risk make immediate sense.