clean-css
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
, andtarget
options are replaced by a singlerebaseTo
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 understats
property;roundingPrecision
is disabled by default;roundingPrecision
applies to all units now, not onlypx
as in 3.x;processImport
andprocessImportFrom
are merged intoinline
option which defaults tolocal
. Remote@import
rules are NOT inlined by default anymore;splits
inliner: { request: ..., timeout: ... }
option intoinlineRequest
andinlineTimeout
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
tospecialComments
;moves
roundingPrecision
andspecialComments
to level 1 optimizations options, see examples;moves
mediaMerging
,restructuring
,semanticMerging
, andshorthandCompacting
to level 2 optimizations options, see examples below;renames
shorthandCompacting
option tomergeIntoShorthands
;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 tominify
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 toinline: ['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 allowsfalse
or'none'
for disabling selector sorting;fetch
option controlling a function for handling remote requests;new
font
shorthand andfont-*
longhand optimizers;removal of
optimizeFont
flag in level 1 optimizations due to newfont
shorthand optimizer;skipProperties
flag in level 2 optimizations controlling which properties won't be optimized;new
animation
shorthand andanimation-*
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 toie10+
; 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 tofalse
; 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 to1
; see optimization levels for examples;rebase
- controls URL rebasing; defaults totrue
;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 whetherminify
method returns a Promise object or not; defaults tofalse
; see promise interface for examples;sourceMap
- controls whether an output source map is built; defaults tofalse
;sourceMapInlineSources
- controls embedding sources inside a source map'ssourcesContent
field; defaults to false.
Compatibility modes
There is a certain number of compatibility mode shortcuts, namely:
new CleanCSS({ compatibility: '*' })
(default) - Internet Explorer 10+ compatibility modenew CleanCSS({ compatibility: 'ie9' })
- Internet Explorer 9+ compatibility modenew CleanCSS({ compatibility: 'ie8' })
- Internet Explorer 8+ compatibility modenew 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 @import
s correctly?
@import
s 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 @import
s 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
intomargin-(bottom|left|right|top)
), optimizing, and restoring them back. You may want to usemergeIntoShorthands
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 asmergeNonAdjacentBy*
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