clean-css

5.3.3 verified Fri May 01 auth: no javascript

A well-tested, fast and efficient CSS minifier for Node.js and browsers. Version 5.3.3 (stable) is released with patch updates over v5.3 (latest major). Clean-css outperforms many alternatives (cssnano, csso) in benchmarks, offering fine-grained optimization levels (0-2), compatibility modes (IE, standards), and source map support. It uses a highly modular plugin system and supports CLI, JavaScript API, and streaming. Engines require Node >= 10.0.

Common errors

error Cannot find module 'clean-css' ↓

cause clean-css not installed or incorrect import path.

fix

Run 'npm install clean-css' and use 'require('clean-css')' or 'import CleanCSS from 'clean-css''.

error CleanCSS is not a constructor ↓

cause Using import { CleanCSS } instead of import CleanCSS (default import).

fix

Use 'import CleanCSS from 'clean-css'' or CommonJS require.

error output.minified is undefined ↓

cause In v5+, output object key is 'styles' not 'minified'.

fix

Access 'output.styles' instead of 'output.minified'.

error TypeError: Cannot read property 'styles' of undefined ↓

cause minify() might have thrown error or invalid input.

fix

Call minify on a valid CSS string; check output.errors for details.

Warnings

breaking Switched to ES module exports. CommonJS require() no longer works. ↓

fix Use dynamic import or ensure package is CJS-compatible. For v5, CommonJS require still works, but future versions may drop it.

deprecated Return type changed from object with .styles to object with .styles (removed .sourceMap, .errors, .warnings in same object). ↓

fix Check output.styles instead of output.minified; errors in output.errors array.

gotcha minify() is synchronous. For large files, use Promise interface with .minify() returns a Promise if option 'returnPromise' is true. ↓

fix Set options.returnPromise = true and await the call.

gotcha CSS custom properties (variables) not optimized by default. ↓

fix Use level 1's variableValueOptimizers option to enable variable optimization.

breaking Level 2 optimizations no longer merge selectors from different media queries by default. ↓

fix Set options.level[2].mergeMedia = true to restore old behavior.

deprecated Semantic merge option removed. ↓

fix Use Level 2 'restructureRules' or 'mergeSemantically' options (check docs).

Install

npm install clean-css

yarn add clean-css

pnpm add clean-css

Imports

CleanCSS
wrong
```
import { CleanCSS } from 'clean-css'
```
correct
```
import CleanCSS from 'clean-css'
```
The library exports a default class; named import does not work. For CommonJS: const CleanCSS = require('clean-css').
CleanCSS (CommonJS)
wrong
```
const { CleanCSS } = require('clean-css')
```
correct
```
const CleanCSS = require('clean-css')
```
Default export. Destructuring from require is incorrect.

minify

wrong

CleanCSS.minify(input, options)

correct

const CleanCSS = require('clean-css'); const output = new CleanCSS(options).minify(input)

minify() is an instance method, not static.

Quickstart

Basic usage: instantiate CleanCSS with options, call minify() on a CSS string, and log the minified output.

const CleanCSS = require('clean-css');
const input = `body { font-size: 16px; color: red; }`;
const options = { level: 2 };
const output = new CleanCSS(options).minify(input);
console.log(output.styles);
// Expected: "body{font-size:16px;color:red}"