Last updated
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
clean-css requires Node.js 4.0+ (tested on Linux, OS X, and Windows)
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.
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.
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.
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.
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.
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.
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:
inline option whitelists which @import rules will be processed, e.g.
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 simply means "no optimizations". Use it when you'd like to inline imports and / or rebase URLs but skip everything else.
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 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.
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.
If you prefer clean-css to return a Promise object then you need to explicitely ask for it, e.g.
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.
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.
@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.
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.
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.
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:
Use the /*! notation instead of the standard one /*:
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.
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:
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.
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;
There is a number of 3rd party plugins to popular build tools:
https://jakubpawlowicz.github.io/clean-css/ (official web interface)
http://refresh-sf.com/
http://adamburgess.github.io/clean-css-online/
See CONTRIBUTING.md.
First clone the sources:
then install dependencies:
then use any of the following commands to verify your copy:
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.
clean-css is released under the MIT License.
