clean-css is a fast and efficient CSS optimizer for Node.js platform and any modern browser.

According to tests it is one of the best available.

Table of Contents

• Node.js version support
• Install
• Use
• What's new in version 5.3
• What's new in version 5.0
• What's new in version 4.2
• What's new in version 4.1
• Important: 4.0 breaking changes
• Constructor options
• Compatibility modes
• Fetch option
• Formatting options
• Inlining options
• Optimization levels
  • Level 0 optimizations
  • Level 1 optimizations
  • Level 2 optimizations
• Plugins
• Minify method
• Promise interface
• CLI utility
• FAQ
• How to optimize multiple files?
• How to process multiple files without concatenating them into one output file?
• How to process remote @imports correctly?
• How to apply arbitrary transformations to CSS properties?
• How to specify a custom rounding precision?
• How to keep a CSS fragment intact?
• How to preserve a comment block?
• How to rebase relative image URLs?
• How to work with source maps?
• How to apply level 1 & 2 optimizations at the same time?
• What level 2 optimizations do?
• What errors and warnings are?
• How to use clean-css with build tools?
• How to use clean-css from web browser?
• Contributing
• How to get started?
• Acknowledgments
• License

Node.js version support

clean-css requires Node.js 10.0+ (tested on Linux, OS X, and Windows)

Install

npm install --save-dev clean-css

Use

var CleanCSS = require('clean-css');
var input = 'a{font-weight:bold;}';
var options = { /* options */ };
var output = new CleanCSS(options).minify(input);

What's new in version 5.3

clean-css 5.3 introduces one new feature:

• variables can be optimized using level 1's variableValueOptimizers option, which accepts a list of value optimizers or a list of their names, e.g. variableValueOptimizers: ['color', 'fraction'].

What's new in version 5.0

clean-css 5.0 introduced some breaking changes:

• Node.js 6.x and 8.x are officially no longer supported;
• transform callback in level-1 optimizations is removed in favor of new plugins interface;
• changes default Internet Explorer compatibility from 10+ to >11, to revert the old default use { compatibility: 'ie10' } flag;
• changes default rebase option from true to false so URLs are not rebased by default. Please note that if you set rebaseTo option it still counts as setting rebase: true to preserve some of the backward compatibility.

And on the new features side of things:

• format options now accepts numerical values for all breaks, which will allow you to have more control over output formatting, e.g. format: {breaks: {afterComment: 2}} means clean-css will add two line breaks after each comment
• a new batch option (defaults to false) is added, when set to true it will process all inputs, given either as an array or a hash, without concatenating them.

What's new in version 4.2

clean-css 4.2 introduces the following changes / features:

• Adds process method for compatibility with optimize-css-assets-webpack-plugin;
• new transition property optimizer;
• preserves any CSS content between /* clean-css ignore:start */ and /* clean-css ignore:end */ comments;
• allows filtering based on selector in transform callback, see example;
• adds configurable line breaks via format: { breakWith: 'lf' } option.

What's new in version 4.1

clean-css 4.1 introduces the following changes / features:

• inline: false as an alias to inline: ['none'];
• multiplePseudoMerging compatibility flag controlling merging of rules with multiple pseudo classes / elements;
• removeEmpty flag in level 1 optimizations controlling removal of rules and nested blocks;
• removeEmpty flag in level 2 optimizations controlling removal of rules and nested blocks;
• compatibility: { selectors: { mergeLimit: <number> } } flag in compatibility settings controlling maximum number of selectors in a single rule;
• minify method improved signature accepting a list of hashes for a predictable traversal;
• selectorsSortingMethod level 1 optimization allows false or 'none' for disabling selector sorting;
• fetch option controlling a function for handling remote requests;
• new font shorthand and font-* longhand optimizers;
• removal of optimizeFont flag in level 1 optimizations due to new font shorthand optimizer;
• skipProperties flag in level 2 optimizations controlling which properties won't be optimized;
• new animation shorthand and animation-* longhand optimizers;
• removeUnusedAtRules level 2 optimization controlling removal of unused @counter-style, @font-face, @keyframes, and @namespace at rules;
• the web interface gets an improved settings panel with "reset to defaults", instant option changes, and settings being persisted across sessions.

Important: 4.0 breaking changes

clean-css 4.0 introduces some breaking changes:

• API and CLI interfaces are split, so API stays in this repository while CLI moves to clean-css-cli;
• root, relativeTo, and target options are replaced by a single rebaseTo option - this means that rebasing URLs and import inlining is much simpler but may not be (YMMV) as powerful as in 3.x;
• debug option is gone as stats are always provided in output object under stats property;
• roundingPrecision is disabled by default;
• roundingPrecision applies to all units now, not only px as in 3.x;
• processImport and processImportFrom are merged into inline option which defaults to local. Remote @import rules are NOT inlined by default anymore;
• splits inliner: { request: ..., timeout: ... } option into inlineRequest and inlineTimeout options;
• remote resources without a protocol, e.g. //fonts.googleapis.com/css?family=Domine:700, are not inlined anymore;
• changes default Internet Explorer compatibility from 9+ to 10+, to revert the old default use { compatibility: 'ie9' } flag;
• renames keepSpecialComments to specialComments;
• moves roundingPrecision and specialComments to level 1 optimizations options, see examples;
• moves mediaMerging, restructuring, semanticMerging, and shorthandCompacting to level 2 optimizations options, see examples below;
• renames shorthandCompacting option to mergeIntoShorthands;
• level 1 optimizations are the new default, up to 3.x it was level 2;
• keepBreaks option is replaced with { format: 'keep-breaks' } to ease transition;
• sourceMap option has to be a boolean from now on - to specify an input source map pass it a 2nd argument to minify method or via a hash instead;
• aggressiveMerging option is removed as aggressive merging is replaced by smarter override merging.

Constructor options

clean-css constructor accepts a hash as a parameter with the following options available:

• compatibility - controls compatibility mode used; defaults to ie10+; see compatibility modes for examples;
• fetch - controls a function for handling remote requests; see fetch option for examples (since 4.1.0);
• format - controls output CSS formatting; defaults to false; see formatting options for examples;
• inline - controls @import inlining rules; defaults to 'local'; see inlining options for examples;
• inlineRequest - controls extra options for inlining remote @import rules, can be any of HTTP(S) request options;
• inlineTimeout - controls number of milliseconds after which inlining a remote @import fails; defaults to 5000;
• level - controls optimization level used; defaults to 1; see optimization levels for examples;
• rebase - controls URL rebasing; defaults to false;
• rebaseTo - controls a directory to which all URLs are rebased, most likely the directory under which the output file will live; defaults to the current directory;
• returnPromise - controls whether minify method returns a Promise object or not; defaults to false; see promise interface for examples;
• sourceMap - controls whether an output source map is built; defaults to false;
• sourceMapInlineSources - controls embedding sources inside a source map's sourcesContent field; defaults to false.

Compatibility modes

There is a certain number of compatibility mode shortcuts, namely:

• new CleanCSS({ compatibility: '*' }) (default) - Internet Explorer 10+ compatibility mode
• new CleanCSS({ compatibility: 'ie9' }) - Internet Explorer 9+ compatibility mode
• new CleanCSS({ compatibility: 'ie8' }) - Internet Explorer 8+ compatibility mode
• new CleanCSS({ compatibility: 'ie7' }) - Internet Explorer 7+ compatibility mode

Each of these modes is an alias to a fine grained configuration, with the following options available:

new CleanCSS({
  compatibility: {
    colors: {
      hexAlpha: false, // controls 4- and 8-character hex color support
      opacity: true // controls `rgba()` / `hsla()` color support
    },
    properties: {
      backgroundClipMerging: true, // controls background-clip merging into shorthand
      backgroundOriginMerging: true, // controls background-origin merging into shorthand
      backgroundSizeMerging: true, // controls background-size merging into shorthand
      colors: true, // controls color optimizations
      ieBangHack: false, // controls keeping IE bang hack
      ieFilters: false, // controls keeping IE `filter` / `-ms-filter`
      iePrefixHack: false, // controls keeping IE prefix hack
      ieSuffixHack: false, // controls keeping IE suffix hack
      merging: true, // controls property merging based on understandability
      shorterLengthUnits: false, // controls shortening pixel units into `pc`, `pt`, or `in` units
      spaceAfterClosingBrace: true, // controls keeping space after closing brace - `url() no-repeat` into `url()no-repeat`
      urlQuotes: true, // controls keeping quoting inside `url()`
      zeroUnits: true // controls removal of units `0` value
    },
    selectors: {
      adjacentSpace: false, // controls extra space before `nav` element
      ie7Hack: true, // controls removal of IE7 selector hacks, e.g. `*+html...`
      mergeablePseudoClasses: [':active', ...], // controls a whitelist of mergeable pseudo classes
      mergeablePseudoElements: ['::after', ...], // controls a whitelist of mergeable pseudo elements
      mergeLimit: 8191, // controls maximum number of selectors in a single rule (since 4.1.0)
      multiplePseudoMerging: true // controls merging of rules with multiple pseudo classes / elements (since 4.1.0)
    },
    units: {
      ch: true, // controls treating `ch` as a supported unit
      in: true, // controls treating `in` as a supported unit
      pc: true, // controls treating `pc` as a supported unit
      pt: true, // controls treating `pt` as a supported unit
      rem: true, // controls treating `rem` as a supported unit
      vh: true, // controls treating `vh` as a supported unit
      vm: true, // controls treating `vm` as a supported unit
      vmax: true, // controls treating `vmax` as a supported unit
      vmin: true // controls treating `vmin` as a supported unit
    }
  }
})

You can also use a string when setting a compatibility mode, e.g.

```js new CleanCSS({