Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 38 ยท Dev Server and HMR

Source Maps

Debug bundled code with Webpack source maps: what a source map is, how mappings work, choosing devtool values for development and production, hidden maps, error tracking and security.

When a browser reports TypeError at main.8f3a2c1b.js:1:48213, you cannot do much with it: the bundle is one long minified line made from hundreds of files. A source map is a separate file that maps positions in the generated code back to positions in your original sources. With it, DevTools shows Cart.js:42 with your real code, and you can set breakpoints in the file you wrote.

You turn source maps on with the devtool option:

JavaScript
module.exports = {
  devtool: 'source-map',
};

Webpack then writes main.js.map next to main.js and appends a comment to the bundle:

JavaScript
//# sourceMappingURL=main.js.map

The browser only downloads the map when DevTools is open, so regular visitors are not affected by its size.

What is inside a map

A source map is JSON with a few fields:

JSON
{
  "version": 3,
  "file": "main.js",
  "sources": ["webpack:///./src/app.js", "webpack:///./src/util.js"],
  "sourcesContent": ["import ...", "export ..."],
  "names": ["greet", "name"],
  "mappings": "AAAA,SAASA,KAAK,CAACC,IAAI..."
}

sources lists the original files, sourcesContent (optional) embeds their text, names holds original identifiers, and mappings is a compact string that links generated positions to original ones. It uses Base64 VLQ encoding, where each segment stores differences from the previous segment, which keeps the map small.

flowchart LR
  G["generated: main.js line 1, col 48213"] --> M["mappings (VLQ)"]
  M --> O["original: src/Cart.js line 42, col 7"]

DevTools reads mappings to convert a generated position into an original one.

Here is a decoder for one VLQ segment so the encoding stops being magic.

Node.js Stand-in: decode a source map mapping

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Choosing a devtool value

devtool values combine keywords: eval, inline, hidden, nosources, cheap, module. Every choice trades build speed, rebuild speed, quality and production safety.

Value Quality Speed Typical use
false none fastest production without maps
eval generated code only fastest rebuild quick dev
eval-cheap-module-source-map original lines, no columns fast recommended development default
eval-source-map original code with columns slower rebuild detailed dev debugging
source-map full, separate .map file slow build production with public maps
hidden-source-map full map, no sourceMappingURL comment slow production with error trackers
nosources-source-map positions and names, no source text slow production without exposing code

In Webpack 5 the mode picks a default: eval in development and false in production (Build Modes). Override it when you need to:

JavaScript
module.exports = (env, argv) => ({
  devtool: argv.mode === 'production' ? 'hidden-source-map' : 'eval-cheap-module-source-map',
});

"Cheap" means line-only mapping (no columns), which is fast. "Module" means loaders' source maps are taken into account, so you see your original TypeScript or JSX instead of the Babel output. With loaders, make sure each one produces maps (sourceMap: true on css-loader and Sass; sourceMap in tsconfig).

Node.js Stand-in: from stack trace to original position

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Production: privacy versus debuggability

A public .map file exposes your original source to anyone. That might be fine for an open source project and unacceptable for a commercial product. Common strategies:

  1. No maps in production (false): simplest, but production errors are cryptic.
  2. Hidden maps (hidden-source-map): generate the files but do not reference them, then upload them to an error tracker (Sentry, Bugsnag and similar). The tracker translates stack traces; users never download the maps.
  3. nosources-source-map: names and positions without the code text.
  4. Serve maps behind authentication or only on an internal host.

If you upload maps to a tracker, delete them from the public folder afterwards. Also keep the [contenthash] of the JS and its map in sync; the tracker needs the exact release.

Troubleshooting

  • DevTools shows generated code. Check that source maps are enabled in browser settings and that the .map file is reachable (Network tab, 404?).
  • Lines are off. A loader does not emit source maps, or cheap hides column details.
  • Breakpoints jump. eval- devtool values give approximate results in some browsers; try eval-source-map.
  • Maps make the build slow. Use an eval-cheap-module-source-map in development and generate the expensive map only for production builds.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a source map link together?

    It translates generated line and column to original file, line and column.
  2. 2. Which devtool is a popular choice for development?

    It is fast to rebuild and maps to original lines, including loader-transformed code.
  3. 3. What does hidden-source-map do?

    Hidden maps are for error trackers: they exist but the browser is not told about them.
  4. 4. Why is a public source map in production a concern?

    Anyone can read sourcesContent or reconstruct code from a public map.

Summary

  • A source map links generated code to original sources through a Base64 VLQ mappings string.
  • devtool picks the trade-off: eval-cheap-module-source-map for development, hidden-source-map or false for production.
  • cheap drops columns, module includes loader maps, hidden omits the reference comment, nosources omits source text.
  • Make sure loaders produce maps too.
  • Treat public maps as published source code, and upload hidden maps to error trackers.

Next: Proxy and History Fallback