Choosing PostCSS Plugins: A Minimal Pipeline for Modern CSS

The Problem: Plugin Overload and Version Drift

Teams adopting PostCSS often add plugins until the pipeline works, then stop. Months later a dependency update breaks the build, or the output bundle grows 40% because a preset enabled every stage‑4 feature. The real decision isn't "which plugins exist" but "which smallest set satisfies our browser support policy without surprising side effects."

Requirements That Drive the Design

• Target browsers: last 2 versions + Safari 14+, no IE11.
• Source syntax: CSS custom properties, container queries, :has(), logical properties.
• Build constraints: CI must finish in < 3 min; CSS output < 150 kB gzipped.
• Team workflow: Incremental migration from a legacy codebase that contains malformed CSS.

These requirements map to four plugin roles: downleveling, baseline normalization, variable handling, and parse resilience.

Smallest Suitable Design

Role	Plugin	Why This One
Downlevel modern syntax	postcss-preset-env	Single entry point for container queries, :has(), nesting, logical properties. Stage config lets us opt in only to what we ship.
Normalize element defaults	postcss-normalize	Replaces a separate reset stylesheet; injects only the normalizations needed for our target browsers.
Transform custom properties	postcss-custom-properties	Preserves var() fallbacks for older browsers while enabling build‑time token substitution for theming.
Handle malformed CSS	postcss-safe-parser	Prevents build failures on legacy files; logs warnings instead of throwing.

No autoprefixer plugin is listed—postcss-preset-env includes it internally when browserslist is present.

Configuration: Explicit Over Implicit

// postcss.config.js
module.exports = {
  parser: require('postcss-safe-parser'),
  plugins: [
    require('postcss-normalize'),
    require('postcss-custom-properties')({
      preserve: true,          // keep var() for runtime theming
      importFrom: 'tokens.css' // design tokens shared across packages
    }),
    require('postcss-preset-env')({
      stage: 3,                // only stable features
      features: {
        'nesting-rules': true,
        'container-queries': true,
        'has-pseudo-class': true,
        'logical-properties-and-values': false // not used yet
      }
    })
  ]
};

Run this in the project root (Node 18+, write access to node_modules). The stage: 3 gate prevents experimental features from inflating output. preserve: true keeps var(--token) in the output so a theme switcher can override at runtime.

Trust and Data Boundaries

• Source tokens (tokens.css) are authored by designers; the pipeline treats them as trusted input.
• Legacy CSS from the migrated codebase is untrusted—malformed selectors, missing braces. postcss-safe-parser isolates parse errors to warnings, but the output may still contain invalid rules. Lint with stylelint in CI as a second gate.
• Browser target data lives in browserslist (package.json or .browserslistrc). Changing it changes autoprefixer behavior without touching plugin code.

Operational Checks

1. Version guard: npx postcss --version must print 8.x. PostCSS 7 plugins will silently fail or crash.
2. Output audit: After a clean build, run npx postcss src/**/*.css -o /tmp/out.css and grep for @supports or --webkit- prefixes. Unexpected prefixes mean browserslist drifted.
3. Bundle size: gzip-size dist/*.css in CI. Fail if > 150 kB.
4. Parser warnings: Capture postcss-safe-parser stdout; any line containing \"parse error\" fails the build.

Failure Modes

Symptom	Root Cause	Mitigation
Build passes but container queries missing in output	stage: 4 or feature flag disabled	Pin features.container-queries: true explicitly
CSS output doubles in size	Preset enabled stage: 0 or all features	Audit with postcss-preset-env --help to list active features
Custom properties not replaced	importFrom path resolves to wrong file	Use absolute path from project root; verify with console.log in config
Safe parser swallows real syntax errors	Warnings only, no exit code	Add a CI step that greps parser output for \"error\"

Conditions That Would Change the Design

• IE11 support added: Enable postcss-custom-properties preserve: false and add postcss-calc for calc() fallbacks.
• Design tokens move to JSON: Replace importFrom: 'tokens.css' with a small plugin that reads tokens.json and injects :root { --token: value }.
• Build time exceeds budget: Drop postcss-normalize and ship a hand‑written 1 kB reset; measure again.
• PostCSS 9 released: Re‑verify every plugin's peerDependency range before upgrading.

Verification Checklist

# 1. Confirm PostCSS 8
npx postcss --version
# 2. Dry‑run one file, inspect output
npx postcss src/components/button.css --config postcss.config.js | head -80
# 3. Full build + size gate
npm run build && gzip-size dist/*.css

If step 2 shows @container rules intact and step 3 stays under 150 kB, the pipeline meets current requirements.