Source maps

After PostCSS, the CSS contains prefixes, unwrapped nesting, joined files — line numbers no longer match your sources. A source map is data that links each line of the output CSS to a line in the source file. With it, the browser's developer tools show post-card.css:4 instead of a line in the built css/main.css.

Two ways to store it

Way	Where the map is	When it is handy
Inline	At the end of the CSS itself, as a base64 string	Quick experiments
External	In a separate `main.css.map` file	Everyday work, the CSS stays compact

Without a config file, postcss-cli writes an inline map by default — you saw it in the installation lesson. The -m (or --map) flag switches to an external one, --no-map turns the map off.

The map in postcss.config.js

When a config file exists, maps are controlled by its map option. Add it next to plugins:

// postcss.config.js
import autoprefixer from 'autoprefixer';
 
export default {
  map: { inline: false },
  plugins: [autoprefixer()],
};

inline: false means "write the map to a separate file". Run npx postcss styles/main.css -o css/main.css. Two files appear in css/, and css/main.css ends with a link to the map:

.post-card {
  padding: 16px;
  -webkit-user-select: none;
     -moz-user-select: none;
          user-select: none;
}
 
/*# sourceMappingURL=main.css.map */

And css/main.css.map contains JSON:

{"version":3,"sources":["../styles/main.css"],"names":[],"mappings":"AAAA;EACE,aAAa;EACb,yBAAiB;KAAjB,sBAAiB;UAAjB,iBAAiB;AACnB","file":"main.css","sourcesContent":[".post-card {\n  padding: 16px;\n  user-select: none;\n}\n"]}

The sources field names the source file, sourcesContent holds its text, and mappings is the encoded line mapping. You never need to read it by hand.

Values of the map option

Value	Result
`{ inline: false }`	A separate `.map` file and a link to it
`true`	The map is embedded at the end of the CSS
`false` or no option	No map

What it looks like in the browser

Open the blog page, then the developer tools (F12), and select the card heading. In the styles panel, next to the .post-card rule, there is a link main.css:1 — to the line in styles/main.css, not in the built file. Clicking it opens the source. Without a map, the link points to css/main.css.

In Vite, CSS source maps in development are turned on with css.devSourcemap: true in vite.config.js.

Common mistake

Passing -m in the command and expecting a .map file when the project has postcss.config.js. With a config file present, postcss-cli takes map settings from it, and the flag changes nothing. Set map in the config file itself.

Thanks for reading!