Mastering Source Maps: From JavaScript to CSS in Webpack

What is a source map?

Source maps are JSON files that map transformed (e.g., minified or compiled) code back to the original source files, allowing browsers to locate the exact position in the original code during debugging.

Key fields of a source map (v3)

version : source map version, currently 3.

file : name of the generated file.

sourceRoot : directory of the original sources; empty if same as output.

sources : array of original source files.

names : all original variable and property names.

mappings : Base64 VLQ‑encoded string that links generated positions to original positions.

Webpack devtool options

Webpack provides many

devtool

settings that combine the base source‑map type (source‑map, eval, inline, cheap, module) with optional features. The most common configurations are illustrated below.

Basic source‑map

Setting

devtool: 'source-map'

generates a separate

.map

file alongside the bundle.

Eval based options

devtool: 'eval'

wraps each module in

eval()

and produces a source map that points to the transformed code.

devtool: 'eval-source-map'

adds the original source map to the eval wrapper, giving full source information while keeping fast rebuilds.

Inline source‑map

devtool: 'inline-source-map'

embeds the source map as a DataURI inside the bundle, so no separate

.map

file is emitted.

Cheap module source‑map

devtool: 'cheap-module-source-map'

provides line‑only mappings (no column information) for faster builds, suitable for development when column precision is not required.

Recommended configurations

Development :

devtool: 'cheap-module-eval-source-map'

– fast rebuilds (eval), full module information, and line‑only mappings (cheap).

Production : Use

devtool: 'hidden-source-map'

to generate a map file for error‑tracking services (e.g., Sentry) without exposing it to browsers, or choose another production‑grade option from the official Webpack documentation.

CSS source maps

CSS can also have source maps; the same JSON format applies. Enabling

sourceMap

in

css-loader

and

sass-loader

propagates the map through the loader chain, allowing the original Sass file to be located from the compiled CSS.

Resolving CSS URL issues with a custom loader

A custom loader can read

sourcesContent

and

sources

from the incoming map, replace relative

url()

references with absolute paths, and pass the transformed content downstream. Example implementation:

<code>module.exports = function(content, map) {
  const { sourcesContent = [], sources = [], sourceRoot = [] } = map || {};
  // locate matching source and replace URLs
  // (implementation omitted for brevity)
  this.callback(null, transformed, map);
};</code>

The loader should be placed before

sass-loader

so that the generated CSS source map contains correct URL resolutions.