clean-css

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

Use

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.

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.

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.

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 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:

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

Fetch option

The fetch option accepts a function which handles remote resource fetching, e.g.

This option provides a convenient way of overriding the default fetching logic if it doesn't support a particular feature, say CONNECT proxies.

Unless given, the default loadRemoteResource logic is used.

Formatting options

By default output CSS is formatted without any whitespace unless a format option is given. First of all there are two shorthands:

and

however format option also accept a fine-grained set of options:

Inlining options

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

Optimization levels

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

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:

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

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:

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

Minify method

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

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

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

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

Promise interface

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

CLI utility

Clean-css has an associated command line utility that can be installed separately using npm install clean-css-cli. For more detailed information, please visit https://github.com/jakubpawlowicz/clean-css-cli.

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 or an array of hashes:

Passing an array of hashes allows you to explicitly specify the order in which the input files are concatenated. Whereas when you use a single hash the order is determined by the traversal order of object properties - available since 4.1.0.

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.:

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:

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.

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

How to keep a CSS fragment intact?

Note: available in the current master, to be released in 4.2.0.

Wrap the CSS fragment in special comments which instruct clean-css to preserve it, e.g.

Optimizing this CSS will result in the following output:

How to preserve a comment block?

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

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.:

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

or even multiple input source maps at once:

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

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

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?

  • https://jakubpawlowicz.github.io/clean-css/ (official web interface)

  • http://refresh-sf.com/

  • http://adamburgess.github.io/clean-css-online/

Contributing

See CONTRIBUTING.md.

How to get started?

First clone the sources:

then install dependencies:

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

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;

  • @davisjam (Jamie Davis) for disclosing ReDOS vulnerabilities;

  • @facelessuser (Isaac) for pointing out a flaw in clean-css' stateless mode;

  • @grandrath (Martin Grandrath) for improving minify method source traversal in ES6;

  • @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.

Last updated

Was this helpful?