CSSO – CSS Optimizer

5.0.5 verified Fri May 01 auth: no javascript

CSSO (CSS Optimizer) is a CSS minifier that performs cleaning (removing redundancies), compression (replacing with shorter forms), and restructuring (merging declarations/rules) to reduce CSS file size. Version 5.0.5 (latest stable) supports ESM and CommonJS dual module, CSS Selectors Level 4, and ships TypeScript definitions. It is built on CSSTree for AST parsing and manipulation. Compared to other minifiers like clean-css, CSSO offers structural optimizations beyond simple compression. Maintained actively with frequent releases.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/csso/dist/csso.js from /path/to/app.js not supported. ↓

cause Trying to require() the ESM bundle instead of CommonJS entry.

fix

Use import or require('csso') which automatically resolves to CommonJS.

error TypeError: csso.minify is not a function ↓

cause Using default import instead of named import: import csso from 'csso' yields the module object, not minify directly.

fix

Use import { minify } from 'csso';

error Cannot find module 'csso/syntax' ↓

cause csso/syntax was added in v5.0.1; trying to use it with an older version.

fix

Update to csso@5.0.1 or later. npm install csso@latest

Warnings

breaking CSSO v5 is ESM by default; CommonJS is supported but requires Node.js >=12.20.0 and using require(). ↓

fix Use import syntax or ensure your project supports CommonJS with require('csso').

breaking Node.js versions <12.20.0, <14.13.0, <15.0.0 are not supported in v5. ↓

fix Upgrade Node.js to ^12.20.0, ^14.13.0, or >=15.0.0.

deprecated CSSO v4 is no longer maintained; upgrade to v5 for latest features and security fixes. ↓

fix npm install csso@latest

gotcha CSSO does not guarantee API stability behind the 'syntax' field; it may change with CSSTree updates. ↓

fix If relying on syntax API, consider using CSSTree directly.

gotcha When using 'csso/syntax', the compress() function returns an object with .ast property, not the AST directly. ↓

fix Use const compressedAst = compress(ast).ast;

gotcha The default export only provides minify(); other functions like compress/parse/generate are under 'csso/syntax'. ↓

fix Import from 'csso/syntax' for step-by-step AST manipulation.

Install

npm install csso

yarn add csso

pnpm add csso

Imports

minify
wrong
```
const { minify } = require('csso');
```
correct
```
import { minify } from 'csso';
```
ESM is recommended; CommonJS also supported via require().
syntax
wrong
```
const syntax = require('csso/syntax');
```
correct
```
import { syntax } from 'csso';
```
The 'syntax' object provides CSSTree API. Access via 'csso/syntax' entry point available since v5.0.1.
compress
wrong
```
import { compress } from 'csso';
```
correct
```
import { compress } from 'csso/syntax';
```
compress() is not exported from the main csso entry. Use 'csso/syntax' for step-by-step AST manipulation.
parse
wrong
```
import syntax from 'csso';
```
correct
```
import { parse } from 'csso/syntax';
```
parse() is part of the CSSTree API available via 'csso/syntax'.

generate

wrong

const { generate } = require('csso/syntax');

correct

import { generate } from 'csso/syntax';

ESM import preferred; generate() converts AST back to CSS string.

Quickstart

Demonstrates two ways to use CSSO: simple minify() call and step-by-step AST compression via syntax module.

import { minify } from 'csso';

const inputCSS = `
  .test {
    color: #ff0000;
    font-weight: bold;
  }
  .test {
    color: green;
  }
`;

const result = minify(inputCSS);
console.log(result.css);
// Output: .test{color:green;font-weight:bold}

// Step-by-step with syntax
import { parse, compress, generate } from 'csso/syntax';

const ast = parse(inputCSS);
const compressed = compress(ast);
const outputCSS = generate(compressed.ast);
console.log(outputCSS);
// Same output