cssnano

cssnano is a modular CSS minifier built on top of the PostCSS ecosystem. Rather than a single monolithic compressor, it composes dozens of independent PostCSS plugins — each handling one optimization, from merging duplicate rules to normalizing color and gradient syntax — into configurable presets.

Three built-in presets (default, lite, advanced) trade off safety for aggressiveness, and cssnano can also load a fully custom plugin list or config file, making it equally suited to drop-in build-tool integration and hand-tuned minification pipelines.

What You Get

• Three ready-made presets — default (safe optimizations), lite (whitespace-focused, minimal risk), and advanced (aggressive transforms like identifier mangling and z-index renumbering) — for different risk tolerances
• Dozens of independently versioned PostCSS plugins (postcss-merge-rules, postcss-colormin, postcss-convert-values, postcss-svgo, and more) that can be composed individually
• Config file discovery (cssnano.config.js, .cssnanorc.json) so projects can override preset choice or plugin options without touching build scripts
• Browserslist-aware transforms that adjust output (autoprefixer handling, vendor-prefix decisions) based on the browsers a project targets
• A hosted documentation site with an interactive playground for testing optimizations against real CSS

Common Use Cases

• Minifying production CSS bundles inside webpack/PostCSS/Vite build pipelines via postcss-loader or a postcss.config.js entry
• Framework integrations that ship cssnano as the default production CSS minifier (Next.js-style and other bundler toolchains)
• CLI/CI minification steps that pipe a build’s compiled CSS through cssnano before deployment
• Custom minification pipelines that hand-pick specific optimization plugins instead of a full preset, for teams needing fine control over allowed transforms

Under The Hood

Architecture

cssnano’s entry point (packages/cssnano/src/index.js) is a thin PostCSS plugin factory that resolves a “preset” — a string alias, a factory function, an already-invoked { plugins: [] } object, or a config file discovered from .cssnanorc.json/cssnano.config.js — into a flat array of [pluginCreator, options] tuples, then hands them to postcss(). Every actual optimization lives in its own workspace package under packages/; the advanced preset is built by layering extra plugins (postcss-discard-unused, postcss-merge-idents, postcss-zindex, css-declaration-sorter) on top of the default preset rather than duplicating its plugin list. Individual optimization packages, such as postcss-merge-rules, further split their own logic into a src/lib/ directory (compatibility checks, rule rewriting, property-relation tables) so each transform’s edge cases stay isolated and independently testable. Because the entire system funnels through resolvePreset/resolveConfig, that indirection is the one place where a change ripples through every preset and every downstream framework integration.

Tech Stack

The project is a pnpm workspace monorepo (pnpm-workspace.yaml with a shared dependency “catalog” for versions like postcss and browserslist) targeting modern Node (^22.22.3 || ^24.15.0 || >=26.0) as native ESM ("type": "module"). Rather than hand-written .ts files, packages are plain JavaScript with JSDoc type annotations checked by tsc -b in emitDeclarationOnly mode across project references for every workspace package, giving full TypeScript strictness without a compile step. Linting and formatting run through oxlint/oxfmt (Rust-based tooling) instead of ESLint/Prettier. Core optimizations build on postcss (peer dependency ^8.5.28), browserslist, autoprefixer, postcss-calc, and postcss-svgo for SVG-in-CSS minification.

Code Quality

Tests run on Node’s built-in test runner (node --test) rather than a third-party framework, with per-package test/ directories that include extensive named regression tests for previously reported bugs (issue26.js, issue927.js, issue1594.js) alongside a dedicated config_loading suite that exercises real temp-directory config discovery. A separate mutation-testing harness (util/mutation-testing/) validates that the test suite actually catches injected faults in select optimization plugins. GitHub Actions run test.yml, performance.yml, and publish.yml workflows, coverage is tracked via Codecov, and Dependabot keeps dependencies current — a mature quality bar for a project this size.

API Design The public surface is a single PostCSS plugin: postcss([cssnano]).process(css), with zero required configuration — the default preset applies automatically. Choosing a different risk profile is a one-line change ({ preset: 'lite' } or { preset: 'advanced' }), and teams needing full control can instead pass an explicit plugins array or drop a cssnano.config.js file that the loader discovers on its own. Documentation lives on a dedicated Astro-based site with a live playground rather than being crammed into the README, keeping the package itself lightweight (a single direct dependency: cssnano-preset-default).