Mastering Source Maps: How Webpack Transforms and Traces Your Code

Anonymous Source Map: The Unsung Hero

When an error occurs during development, the console can point to the exact line in the original source code even though the bundled output contains only transformed and minified JavaScript. This is possible thanks to source maps , which preserve the mapping between original and compiled code.

Typical frontend build steps include:

Transpiling JSX, TSX, or TypeScript to runtime‑compatible JavaScript.

Converting modern JavaScript to ES5 for broader browser support.

Bundling multiple files into a single, often minified, output.

After these steps the original information is lost, making debugging difficult. A source map records the necessary metadata to reconstruct the original sources.

Source Map Principles

Composition of a Source Map

A minimal example shows how a simple arrow function is compiled and a source map is generated:

// input
const example = () => {
  console.log('example');
}

// output
"use strict";
var example = function example() {
  console.log("example");
};

The corresponding source map (JSON) contains:

{
  "version": 3,
  "sources": ["src/example.js"],
  "names": ["example","console","log"],
  "mappings": ";;AAAA,IAAMA,OAAO,GAAG,SAAVA,OAAU,GAAM;AACpBC,EAAAA,OAAO,CAACC,GAAR,CAAY,SAAZ;AACD,CAFD",
  "sourcesContent": ["const example = () => {
  console.log(\"example\");
};
"]
}

The most important field is mappings, which records the relationship between generated and original positions.

How Mappings Record the Mapping

Each generated token is paired with its original file name, line, column, and name index. The article originally included a table illustrating this; the essential idea is that the mapping records a series of tuples like

generatedLine,generatedColumn|sourceIndex|originalLine,originalColumn|nameIndex

.

Optimizations

Use semicolons to separate lines instead of explicit line numbers.

Replace variable names with indices from the names array.

Replace file names with indices from the sources array.

Store positions as relative offsets rather than absolute values.

These steps dramatically reduce the size of the mappings string.

VLQ Encoding

To shrink the mapping further, source maps use a Base64 VLQ (Variable‑Length Quantity) encoding. Each number is represented by a series of 6‑bit groups; the most‑significant bit indicates continuation, and another bit encodes the sign. The encoded groups are then concatenated and Base64‑encoded, turning a sequence like 4|0|0|6|0 into IAAMA.

Webpack Source Map Types

Webpack can generate source maps for each transformation step. The devtool option selects the mode:

source-map : Generates an external .map file; most detailed but slower.

inline-source-map : Embeds the map as a Base64 string inside the bundle; increases bundle size.

eval : Wraps modules in eval() without a map; only a sourceURL is added.

eval-source-map : Uses eval() plus an inline map; shows original source in the console.

cheap-source-map : Records only line numbers (no column information).

cheap-module-source-map : Records line numbers for the original source before loader transformations.

nosources-source-map : Generates a map without the original source content.

hidden-source-map : Generates a map file but does not reference it in the bundle.

Complex combinations can be expressed with a regular expression like

"^(inline-|hidden-|eval-)?(nosources-)?(cheap-(module-)?)?source-map$"

.

Which Mode for Development vs. Production?

During development, eval-source-map offers fast builds and full source visibility. For production, hidden-source-map protects source code while still allowing error reporting.

Why Do Source Maps Sometimes Appear Inaccurate?

Some modes sacrifice information for speed (e.g., eval, cheap-source-map). If the hot‑reloading server uses an unsuitable mode, line numbers may be off. Switching to cheap-module-source-map or source-map usually resolves the issue. Additionally, any loader that strips original information can cause mismatches.

Note: If a number cannot be expressed in a single VLQ group, it is split into multiple groups. For example, 23 (binary 10111) becomes two groups: 101110 000001 .

References

https://www.npmjs.com/package/merge-source-map

D‑kylin/note – VLQ encoding documentation

Rich‑Harris/vlq – VLQ implementation

细说 js 压缩、sourcemap、通过 sourcemap 查找原始报错信息 – https://segmentfault.com/a/1190000016987829