Clean-CSS is a fast and efficient CSS optimizer for Node.js that provides comprehensive CSS minification capabilities including property optimization, whitespace removal, color optimization, and advanced level 2 optimizations like rule merging and restructuring. It offers a flexible plugin system, supports source maps, handles @import inlining, and provides both synchronous and asynchronous APIs with Promise support.
npm install clean-cssconst CleanCSS = require('clean-css');Note: clean-css is a CommonJS module. For ES modules, use dynamic import:
const { default: CleanCSS } = await import('clean-css');const CleanCSS = require('clean-css');
// Basic minification
const input = 'a { font-weight: bold; }';
const output = new CleanCSS().minify(input);
console.log(output.styles); // 'a{font-weight:bold}'
// With options
const options = { level: 2 };
const optimizer = new CleanCSS(options);
const result = optimizer.minify(input);/**
* Main CleanCSS class for CSS minification
*/
class CleanCSS {
/**
* @param {CleanCSSOptions} [options] - Configuration options
*/
constructor(options) {}
/**
* Minify CSS input
* @param {string|string[]|object} input - CSS content, file paths, or file hash
* @param {object} [sourceMap] - Input source map
* @param {function} [callback] - Callback function for async operation
* @returns {MinifyResult|Promise<MinifyResult>} Minification result
*/
minify(input, sourceMap, callback) {}
/**
* Static helper method for webpack compatibility
* @param {string|string[]|object} input - CSS input
* @param {object} opts - Options object
* @returns {Promise<{css: string}>} Promise resolving to minified CSS
*/
static process(input, opts) {}
}
/**
* Result object returned by minify method
* @typedef {object} MinifyResult
* @property {string} styles - Minified CSS output
* @property {string[]} errors - Array of error messages
* @property {string[]} warnings - Array of warning messages
* @property {object} stats - Minification statistics
* @property {number} stats.efficiency - Compression ratio (0-1)
* @property {number} stats.minifiedSize - Size after minification (bytes)
* @property {number} stats.originalSize - Original size (bytes)
* @property {number} stats.timeSpent - Processing time (milliseconds)
* @property {string[]} inlinedStylesheets - List of inlined stylesheet paths
* @property {object} [sourceMap] - Generated source map (if enabled)
*/Clean-CSS provides extensive configuration options for controlling minification behavior, compatibility modes, and output formatting.
/**
* Configuration options for CleanCSS constructor
* @typedef {object} CleanCSSOptions
* @property {boolean} [batch=false] - Process multiple inputs without concatenating
* @property {string|object} [compatibility='*'] - Browser compatibility mode
* @property {string|object} [format=false] - Output formatting options
* @property {string|string[]} [inline='local'] - @import inlining strategy
* @property {number|object} [level=1] - Optimization level (0, 1, 2)
* @property {boolean} [rebase=false] - Enable URL rebasing
* @property {string} [rebaseTo] - Target directory for URL rebasing
* @property {boolean} [returnPromise=false] - Return Promise interface
* @property {boolean} [sourceMap=false] - Generate source maps
* @property {boolean} [sourceMapInlineSources=false] - Embed sources in source map
* @property {function} [fetch] - Custom function for fetching remote resources
* @property {object} [inlineRequest] - HTTP request options for remote @imports
* @property {number} [inlineTimeout=5000] - Timeout for remote resource fetching
* @property {object} [plugins] - Custom optimization plugins
*/Constructor Options and Configuration
Control the level of optimization applied to your CSS, from basic cleanup to advanced structural optimizations.
interface OptimizationLevelObject {
0?: object; // No optimizations
1?: Level1Options; // Property-level optimizations
2?: Level2Options; // Rule-level optimizations
}Support for multiple input formats including strings, file paths, and batch processing with comprehensive output metadata.
// Input types
type CleanCSSInput =
| string // Raw CSS
| string[] // File paths
| Record<string, FileObject> // File hash
| Buffer; // CSS buffer
interface FileObject {
styles: string;
sourceMap?: object;
}Process multiple CSS files independently or use Promise-based workflows for async operations.
interface BatchResult {
[filename: string]: MinifyResult;
}Batch Processing and Promise Interface
Configure Clean-CSS for specific browser compatibility requirements and CSS feature support.
/**
* Browser compatibility configuration object
* @typedef {object} CompatibilityObject
* @property {object} [colors] - Color compatibility settings
* @property {boolean} [colors.hexAlpha] - 4- and 8-character hex color support
* @property {boolean} [colors.opacity] - rgba() and hsla() color support
* @property {object} [customUnits] - Custom units compatibility
* @property {boolean} [customUnits.rpx] - Support for rpx units
* @property {object} [properties] - CSS property compatibility settings
* @property {object} [selectors] - CSS selector compatibility settings
* @property {object} [units] - CSS unit compatibility settings
*/Compatibility and Browser Support
Source map generation, @import inlining, URL rebasing, and custom plugin system for extending functionality.
/**
* Plugin system for extending Clean-CSS functionality
* @typedef {object} PluginObject
* @property {Plugin[]} [plugins] - Array of plugin objects
*/
/**
* Individual plugin with level-specific transformations
* @typedef {object} Plugin
* @property {object} [level1] - Level 1 transformations
* @property {function} [level1.property] - Transform properties: (rule, property) => void
* @property {function} [level1.value] - Transform values: (propertyName, propertyValue) => string
* @property {object} [level2] - Level 2 transformations
* @property {function} [level2.block] - Transform token blocks: (tokens) => void
*/