A few seconds.

clean-css

A well-tested CSS minifier


clean-css logo

NPM version Linux Build Status Windows Build status Dependency Status NPM Downloads Twitter

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

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

Install

npm install clean-css

Use

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

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;
  • 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 true;
  • 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: {
      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: false, // 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
    },
    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.

new CleanCSS({
  compatibility: 'ie9,-properties.merging' // sets compatibility to IE9 mode with disabled property merging
})

Formatting options

The format option accept the following options:

new CleanCSS({
  format: {
    breaks: { // controls where to insert breaks
      afterAtRule: false, // controls if a line break comes after an at-rule; e.g. `@charset`; defaults to `false`
      afterBlockBegins: false, // controls if a line break comes after a block begins; e.g. `@media`; defaults to `false`
      afterBlockEnds: false, // controls if a line break comes after a block ends, defaults to `false`
      afterComment: false, // controls if a line break comes after a comment; defaults to `false`
      afterProperty: false, // controls if a line break comes after a property; defaults to `false`
      afterRuleBegins: false, // controls if a line break comes after a rule begins; defaults to `false`
      afterRuleEnds: false, // controls if a line break comes after a rule ends; defaults to `false`
      beforeBlockEnds: false, // controls if a line break comes before a block ends; defaults to `false`
      betweenSelectors: false // controls if a line break comes between selectors; defaults to `false`
    },
    indentBy: 0, // controls number of characters to indent with; defaults to `0`
    indentWith: 'space', // controls a character to indent with, can be `'space'` or `'tab'`; defaults to `'space'`
    spaces: { // controls where to insert spaces
      aroundSelectorRelation: false, // controls if spaces come around selector relations; e.g. `div > a`; defaults to `false`
      beforeBlockBegins: false, // controls if a space comes before a block begins; e.g. `.block {`; defaults to `false`
      beforeValue: false // controls if a space comes before a value; e.g. `width: 1rem`; defaults to `false`
    },
    wrapAt: false // controls maximum line length; defaults to `false`
  }
})

Inlining options

inline option whitelists which @import rules will be processed, e.g.

new CleanCSS({
  inline: ['local'] // default
})
new CleanCSS({
  inline: ['all'] // same as ['local', 'remote']
})
new CleanCSS({
  inline: ['local', 'mydomain.example.com']
})
new CleanCSS({
  inline: ['local', 'remote', '!fonts.googleapis.com']
})

Optimization levels

The level option can be either 0, 1 (default), or 2, e.g.

new CleanCSS({
  level: 2
})

or a fine-grained configuration given via a hash.

Please note that level 1 optimization options are generally safe while level 2 optimizations should be safe for most users.

Level 0 optimizations

Level 0 optimizations simply means "no optimizations". Use it when you'd like to inline imports and / or rebase URLs but skip everything else.

Level 1 optimizations

Level 1 optimizations (default) operate on single properties only, e.g. can remove units when not required, turn rgb colors to a shorter hex representation, remove comments, etc

Here is a full list of available options:

new CleanCSS({
  level: {
    1: {
      cleanupCharsets: true, // controls [email protected]` moving to the front of a stylesheet; defaults to `true`
      normalizeUrls: true, // controls URL normalization; defaults to `true`
      optimizeBackground: true, // controls `background` property optimizatons; defaults to `true`
      optimizeBorderRadius: true, // controls `border-radius` property optimizatons; defaults to `true`
      optimizeFilter: true, // controls `filter` property optimizatons; defaults to `true`
      optimizeFont: true, // ontrols `font` property optimizatons; defaults to `true`
      optimizeFontWeight: true, // controls `font-weight` property optimizatons; defaults to `true`
      optimizeOutline: true, // controls `outline` property optimizatons; defaults to `true`
      removeNegativePaddings: true, // controls removing negative paddings; defaults to `true`
      removeQuotes: true, // controls removing quotes when unnecessary; defaults to `true`
      removeWhitespace: true, // controls removing unused whitespace; defaults to `true`
      replaceMultipleZeros: true, // contols removing redundant zeros; defaults to `true`
      replaceTimeUnits: true, // controls replacing time units with shorter values; defaults to `true`
      replaceZeroUnits: true, // controls replacing zero values with units; defaults to `true`
      roundingPrecision: false, // rounds pixel values to `N` decimal places; `false` disables rounding; defaults to `false`
      selectorsSortingMethod: 'standard', // denotes selector sorting method; can be `natural` or `standard`; defaults to `standard`
      specialComments: 'all', // denotes a number of /*! ... */ comments preserved; defaults to `all`
      tidyAtRules: true, // controls at-rules (e.g. [email protected]`, `@import`) optimizing; defaults to `true`
      tidyBlockScopes: true, // controls block scopes (e.g. [email protected]`) optimizing; defaults to `true`
      tidySelectors: true, // controls selectors optimizing; defaults to `true`,
      transform: function () {} // defines a callback for fine-grained property optimization; defaults to no-op
    }
  }
});

There is an all shortcut for toggling all options at the same time, e.g.

new CleanCSS({
  level: {
    1: {
      all: false, // set all values to `false`
      tidySelectors: true // turns on optimizing selectors
    }
  }
});

Level 2 optimizations

Level 2 optimizations operate at rules or multiple properties level, e.g. can remove duplicate rules, remove properties redefined further down a stylesheet, or restructure rules by moving them around.

Please note that if level 2 optimizations are turned on then, unless explicitely disabled, level 1 optimizations are applied as well.

Here is a full list of available options:

new CleanCSS({
  level: {
    2: {
      mergeAdjacentRules: true, // controls adjacent rules merging; defaults to true
      mergeIntoShorthands: true, // controls merging properties into shorthands; defaults to true
      mergeMedia: true, // controls [email protected]` merging; defaults to true
      mergeNonAdjacentRules: true, // controls non-adjacent rule merging; defaults to true
      mergeSemantically: false, // controls semantic merging; defaults to false
      overrideProperties: true, // controls property overriding based on understandability; defaults to true
      reduceNonAdjacentRules: true, // controls non-adjacent rule reducing; defaults to true
      removeDuplicateFontRules: true, // controls duplicate [email protected]` removing; defaults to true
      removeDuplicateMediaBlocks: true, // controls duplicate [email protected]` removing; defaults to true
      removeDuplicateRules: true, // controls duplicate rules removing; defaults to true
      restructureRules: false // controls rule restructuring; defaults to false
    }
  }
});

There is an all shortcut for toggling all options at the same time, e.g.

new CleanCSS({
  level: {
    2: {
      all: false, // sets all values to `false`
      removeDuplicateRules: true // turns on removing duplicate rules
    }
  }
});

Minify method

Once configured clean-css provides a minify method to optimize a given CSS, e.g.

var output = new CleanCSS(options).minify(source);

The output of the minify method is a hash with following fields:

console.log(output.styles); // optimized output CSS as a string
console.log(output.sourceMap); // output source map if requested with `sourceMap` option
console.log(output.errors); // a list of errors raised
console.log(output.warnings); // a list of warnings raised
console.log(output.stats.originalSize); // original content size after import inlining
console.log(output.stats.minifiedSize); // optimized content size
console.log(output.stats.timeSpent); // time spent on optimizations in milliseconds
console.log(output.stats.efficiency); // a ratio of output size to input size (e.g. 25% if content was reduced from 100 bytes to 75 bytes)

The minify method also accepts an input source map, e.g.

var output = new CleanCSS(options).minify(source, inputSourceMap);

or a callback invoked when optimizations are finished, e.g.

new CleanCSS(options).minify(source, function (error, output) {
  // `output` is the same as in the synchronous call above
});

Promise interface

If you prefer clean-css to return a Promise object then you need to explicitely ask for it, e.g.

new CleanCSS({ returnPromise: true })
  .minify(source)
  .then(function (output) { console.log(output.styles); })
  .catch(function (error) { // deal with errors });

FAQ

How to optimize multiple files?

It can be done either by passing an array of paths, or, when sources are already available, a hash:

new CleanCSS().minify(['path/to/file/one', 'path/to/file/two']);
new CleanCSS().minify({
  'path/to/file/one': {
    styles: 'contents of file one'
  },
  'path/to/file/two': {
    styles: 'contents of file two'
  }
});

Important note - any @import rules already present in the hash will be resolved in memory.

How to process remote @imports correctly?

In order to inline remote @import statements you need to provide a callback to minify method as fetching remote assets is an asynchronous operation, e.g.:

var source = [email protected] url(http://example.com/path/to/remote/styles);';
new CleanCSS({ inline: ['remote'] }).minify(source, function (error, output) {
  // output.styles
});

If you don't provide a callback, then remote @imports will be left as is.

How to apply arbitrary transformations to CSS properties?

If clean-css doesn't perform a particular property optimization, you can use transform callback to apply it:

var source = '.block{background-image:url(/path/to/image.png)}';
var output = new CleanCSS({
  level: {
    1: {
      transform: function (propertyName, propertyValue) {
        if (propertyName == 'background-image' && propertyValue.indexOf('/path/to') > -1) {
          return propertyValue.replace('/path/to', '../valid/path/to');
        }
      }
    }
  }
}).minify(source);

console.log(output.styles); # => .block{background-image:url(../valid/path/to/image.png)}

Note: returning false from transform callback will drop a property.

How to specify a custom rounding precision?

The level 1 roundingPrecision optimization option accept a string with per-unit rounding precision settings, e.g.

new CleanCSS({
  level: {
    1: {
      roundingPrecision: 'all=3,px=5'
    }
  }
}).minify(source)

which sets all units rounding precision to 3 digits except px unit precision of 5 digits.

How to preserve a comment block?

Use the /*! notation instead of the standard one /*:

/*!
  Important comments included in optimized output.
*/

How to rebase relative image URLs?

clean-css will handle it automatically for you in the following cases:

  • when full paths to input files are passed in as options;
  • when correct paths are passed in via a hash;
  • when rebaseTo is used with any of above two.

How to work with source maps?

To generate a source map, use sourceMap: true option, e.g.:

new CleanCSS({ sourceMap: true, rebaseTo: pathToOutputDirectory })
  .minify(source, function (error, output) {
    // access output.sourceMap for SourceMapGenerator object
    // see https://github.com/mozilla/source-map/#sourcemapgenerator for more details
});

You can also pass an input source map directly as a 2nd argument to minify method:

new CleanCSS({ sourceMap: true, rebaseTo: pathToOutputDirectory })
  .minify(source, inputSourceMap, function (error, output) {
    // access output.sourceMap to access SourceMapGenerator object
    // see https://github.com/mozilla/source-map/#sourcemapgenerator for more details
});

or even multiple input source maps at once:

new CleanCSS({ sourceMap: true, rebaseTo: pathToOutputDirectory }).minify({
  'path/to/source/1': {
    styles: '...styles...',
    sourceMap: '...source-map...'
  },
  'path/to/source/2': {
    styles: '...styles...',
    sourceMap: '...source-map...'
  }
}, function (error, output) {
  // access output.sourceMap as above
});

How to apply level 1 & 2 optimizations at the same time?

Using the hash configuration specifying both optimization levels, e.g.

new CleanCSS({
  level: {
    1: {
      all: true,
      normalizeUrls: false
    },
    2: {
      restructureRules: true
    }
  }
})

will apply level 1 optimizations, except url normalization, and default level 2 optimizations with rule restructuring.

What level 2 optimizations do?

All level 2 optimizations are dispatched here, and this is what they do:

  • recursivelyOptimizeBlocks - does all the following operations on a nested block, like @media or @keyframe;
  • recursivelyOptimizeProperties - optimizes properties in rulesets and flat at-rules, like @font-face, by splitting them into components (e.g. margin into margin-(bottom|left|right|top)), optimizing, and restoring them back. You may want to use mergeIntoShorthands option to control whether you want to turn multiple components into shorthands;
  • removeDuplicates - gets rid of duplicate rulesets with exactly the same set of properties, e.g. when including a Sass / Less partial twice for no good reason;
  • mergeAdjacent - merges adjacent rulesets with the same selector or rules;
  • reduceNonAdjacent - identifies which properties are overridden in same-selector non-adjacent rulesets, and removes them;
  • mergeNonAdjacentBySelector - identifies same-selector non-adjacent rulesets which can be moved (!) to be merged, requires all intermediate rulesets to not redefine the moved properties, or if redefined to have the same value;
  • mergeNonAdjacentByBody - same as the one above but for same-selector non-adjacent rulesets;
  • restructure - tries to reorganize different-selector different-rules rulesets so they take less space, e.g. .one{padding:0}.two{margin:0}.one{margin-bottom:3px} into .two{margin:0}.one{padding:0;margin-bottom:3px};
  • removeDuplicateFontAtRules - removes duplicated @font-face rules;
  • removeDuplicateMediaQueries - removes duplicated @media nested blocks;
  • mergeMediaQueries - merges non-adjacent @media at-rules by the same rules as mergeNonAdjacentBy* above;

How to use clean-css with build tools?

There is a number of 3rd party plugins to popular build tools:

How to use clean-css from web browser?

Contributing

See CONTRIBUTING.md.

How to get started?

First clone the sources:

git clone git@github.com:jakubpawlowicz/clean-css.git

then install dependencies:

cd clean-css
npm install

then use any of the following commands to verify your copy:

npm run bench # for clean-css benchmarks (see [test/bench.js](https://github.com/jakubpawlowicz/clean-css/blob/master/test/bench.js) for details)
npm run browserify # to create the browser-ready clean-css version
npm run check # to lint JS sources with [JSHint](https://github.com/jshint/jshint/)
npm test # to run all tests

Acknowledgments

Sorted alphabetically by GitHub handle:

  • @abarre (Anthony Barre) for improvements to @import processing;
  • @alexlamsl (Alex Lam S.L.) for testing early clean-css 4 versions, reporting bugs, and suggesting numerous improvements.
  • @altschuler (Simon Altschuler) for fixing @import processing inside comments;
  • @ben-eb (Ben Briggs) for sharing ideas about CSS optimizations;
  • @facelessuser (Isaac) for pointing out a flaw in clean-css' stateless mode;
  • @jmalonzo (Jan Michael Alonzo) for a patch removing node.js' old sys package;
  • @lukeapage (Luke Page) for suggestions and testing the source maps feature; Plus everyone else involved in #125 for pushing it forward;
  • @madwizard-thomas for sharing ideas about @import inlining and URL rebasing.
  • @ngyikp (Ng Yik Phang) for testing early clean-css 4 versions, reporting bugs, and suggesting numerous improvements.
  • @wagenet (Peter Wagenet) for suggesting improvements to @import inlining behavior;
  • @venemo (Timur Krist√≥f) for an outstanding contribution of advanced property optimizer for 2.2 release;
  • @vvo (Vincent Voyer) for a patch with better empty element regex and for inspiring us to do many performance improvements in 0.4 release;
  • @xhmikosr for suggesting new features, like option to remove special comments and strip out URLs quotation, and pointing out numerous improvements like JSHint, media queries, etc.

License

clean-css is released under the MIT License.

Pincer is a project which aims to provide best library discovery tools for developers. We're growing day by day. We have only npm platform for now but we will add the others as much as we can.