Balancing CSS minification and source map precision in PostCSS

Answer to the Core Question

Generate the source map only after the entire plugin chain has finished, and enable it only for the final minification step. Place the minifier as the last plugin, turn off source‑map generation for all intermediate plugins, and let PostCSS emit a single map that reflects the fully transformed, minified CSS. This preserves debugging accuracy and keeps the memory footprint low.

Why the Order Matters

• Source maps created before minification describe the unminified AST, not the final output, so the browser will jump to wrong lines.
• Minification can collapse selectors, remove whitespace, and merge rules, all of which alter the mapping. A map generated after these changes is the only one that can accurately map back to the original source.

Configuration Strategy

1. Disable intermediate maps – Set sourceMap: false (or omit the map option) on every plugin except the last one.
2. Place the minifier last – e.g., cssnano, purgecss, or any other minification plugin that supports source‑map preservation.
3. Enable map on the minifier – Pass sourceMap: true (or map: true depending on the plugin) so that PostCSS can generate a map that covers the final output.
4. Let PostCSS handle map generation – Do not call postcss().process(..., { map: true }) before the minifier; let the minifier’s options drive the map.
5. Optional streaming – For very large CSS, use postcss().process(..., { from: , to: , map: { inline: false } }) and stream the output to reduce peak memory.

Example postcss.config.js

module.exports = {
  plugins: [
    require('postcss-import'),
    require('postcss-preset-env')({ stage: 0 }),
    // Other AST‑altering plugins – no sourceMap option
    require('cssnano')({ preset: ['default', { map: { inline: false } }] })
  ]
};

Verification Checklist

• Run npm run build -- --source-map and inspect the generated .css.map file for mappings that cover the minified CSS.
• Open the minified CSS in a browser dev‑tools console, enable source maps, and confirm that clicking a rule highlights the correct original source line.
• Measure Node.js memory usage during the build with process.memoryUsage() and compare it to a build that generates maps at every step.
• Check the plugin’s documentation for the exact option name (e.g., map vs sourceMap) to avoid misconfiguration.

Missing Diagnostic Detail

To tailor this advice to your exact setup, could you let us know which minification plugin you are using (e.g., cssnano, purgecss, postcss-combine-media-query)? The option names for enabling source maps can differ between plugins.