clean-css is a fast and efficient CSS optimizer for [Node.js](http://nodejs.org/) platform and [any modern browser](https://jakubpawlowicz.github.io/clean-css).
According to [tests](http://goalsmashers.github.io/css-minification-benchmark/) it is one of the best available.
**Table of Contents**
- [Node.js version support](#nodejs-version-support)
* [How to use clean-css with build tools?](#how-to-use-clean-css-with-build-tools)
* [How to use clean-css from web browser?](#how-to-use-clean-css-from-web-browser)
- [Contributing](#contributing)
* [How to get started?](#how-to-get-started)
- [Acknowledgments](#acknowledgments)
- [License](#license)
# Node.js version support
clean-css requires Node.js 4.0+ (tested on Linux, OS X, and Windows)
# Install
```
npm install clean-css
```
# Use
```js
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](https://github.com/jakubpawlowicz/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](https://jakubpawlowicz.github.io/clean-css) gets an improved settings panel with "reset to defaults", instant option changes, and settings being persisted across sessions.
*`format` - controls output CSS formatting; defaults to `false`; see [formatting options](#formatting-options) for examples;
*`inline` - controls `@import` inlining rules; defaults to `'local'`; see [inlining options](#inlining-options) for examples;
*`inlineRequest` - controls extra options for inlining remote `@import` rules, can be any of [HTTP(S) request options](https://nodejs.org/api/http.html#http_http_request_options_callback);
*`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](#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](#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](https://github.com/jakubpawlowicz/clean-css/blob/master/lib/options/compatibility.js), with the following options available:
```js
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
The `fetch` option accepts a function which handles remote resource fetching, e.g.
```js
var request = require('request');
var source = '@import url(http://example.com/path/to/stylesheet.css);';
new CleanCSS({
fetch: function (uri, inlineRequest, inlineTimeout, callback) {
request(uri, function (error, response, body) {
if (error) {
callback(error, null);
} else if (response && response.statusCode != 200) {
callback(response.statusCode, null);
} else {
callback(null, body);
}
});
}
}).minify(source);
```
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](https://github.com/jakubpawlowicz/clean-css/blob/master/lib/reader/load-remote-resource.js) logic is used.
The `level` option can be either `0`, `1` (default), or `2`, e.g.
```js
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:
```js
new CleanCSS({
level: {
1: {
cleanupCharsets: true, // controls `@charset` moving to the front of a stylesheet; defaults to `true`
normalizeUrls: true, // controls URL normalization; defaults to `true`
selectorsSortingMethod: 'standard', // denotes selector sorting method; can be `'natural'` or `'standard'`, `'none'`, or false (the last two since 4.1.0); defaults to `'standard'`
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.
```js
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:
```js
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 `@media` 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
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.
{'path/to/file/one': {styles: 'contents of file one'}},
{'path/to/file/two': {styles: 'contents of file two'}}
]);
```
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](http://2ality.com/2015/10/property-traversal-order-es6.html) - 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?
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.:
```js
var source = '@import 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 `@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:
```js
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) {
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.
```js
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 `/*`:
```css
/*!
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.:
```js
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:
```js
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:
```js
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.
```js
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](https://github.com/jakubpawlowicz/clean-css/blob/master/lib/optimizer/level-2/optimize.js#L67), 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}`;
* [@jmalonzo](https://github.com/jmalonzo) (Jan Michael Alonzo) for a patch removing node.js' old `sys` package;
* [@lukeapage](https://github.com/lukeapage) (Luke Page) for suggestions and testing the source maps feature;
Plus everyone else involved in [#125](https://github.com/jakubpawlowicz/clean-css/issues/125) for pushing it forward;
* [@madwizard-thomas](https://github.com/madwizard-thomas) for sharing ideas about `@import` inlining and URL rebasing.
* [@ngyikp](https://github.com/ngyikp) (Ng Yik Phang) for testing early clean-css 4 versions, reporting bugs, and suggesting numerous improvements.
* [@wagenet](https://github.com/wagenet) (Peter Wagenet) for suggesting improvements to `@import` inlining behavior;
* [@venemo](https://github.com/venemo) (Timur Kristóf) for an outstanding contribution of advanced property optimizer for 2.2 release;
* [@vvo](https://github.com/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](https://github.com/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](https://github.com/jakubpawlowicz/clean-css/blob/master/LICENSE).
