[](https://www.npmjs.com/package/clean-css) [](https://travis-ci.org/jakubpawlowicz/clean-css) [](https://ci.appveyor.com/project/jakubpawlowicz/clean-css/branch/master) [](https://david-dm.org/jakubpawlowicz/clean-css) [](https://www.npmjs.com/package/clean-css) [](https://twitter.com/cleancss) 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) - [Install](#install) - [Use](#use) * [Important: 4.0 breaking changes](#important-40-breaking-changes) * [Constructor options](#constructor-options) * [Compatibility modes](#compatibility-modes) * [Formatting options](#formatting-options) * [Inlining options](#inlining-options) * [Optimization levels](#optimization-levels) + [Level 0 optimizations](#level-0-optimizations) + [Level 1 optimizations](#level-1-optimizations) + [Level 2 optimizations](#level-2-optimizations) * [Minify method](#minify-method) * [Promise interface](#promise-interface) - [FAQ](#faq) * [How to optimize multiple files?](#how-to-optimize-multiple-files) * [How to process remote `@import`s correctly?](#how-to-process-remote-imports-correctly) * [How to apply arbitrary transformations to CSS properties?](#how-to-apply-arbitrary-transformations-to-css-properties) * [How to specify a custom rounding precision?](#how-to-specify-a-custom-rounding-precision) * [How to preserve a comment block?](#how-to-preserve-a-comment-block) * [How to rebase relative image URLs?](#how-to-rebase-relative-image-urls) * [How to work with source maps?](#how-to-work-with-source-maps) * [How to apply level 1 & 2 optimizations at the same time?](#how-to-apply-level-1--2-optimizations-at-the-same-time) * [What level 2 optimizations do?](#what-level-2-optimizations-do) * [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. ## 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](#compatibility-modes) for examples; * `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 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. ```js new CleanCSS({ compatibility: 'ie9,-properties.merging' // sets compatibility to IE9 mode with disabled property merging }) ``` ## Formatting options The `format` option accept the following options: ```js 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. ```js new CleanCSS({ inline: ['local'] // default }) ``` ```js new CleanCSS({ inline: ['all'] // same as ['local', 'remote'] }) ``` ```js new CleanCSS({ inline: ['local', 'mydomain.example.com'] }) ``` ```js new CleanCSS({ inline: ['local', 'remote', '!fonts.googleapis.com'] }) ``` ## Optimization levels 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` 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. `@charset`, `@import`) optimizing; defaults to `true` tidyBlockScopes: true, // controls block scopes (e.g. `@media`) 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. ```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 reduceNonAdjacentRules: true, // controls non-adjacent rule reducing; defaults to true removeDuplicateFontRules: true, // controls duplicate `@font-face` removing; defaults to true removeDuplicateMediaBlocks: true, // controls duplicate `@media` 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. ```js 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. ```js var output = new CleanCSS(options).minify(source); ``` The output of the `minify` method is a hash with following fields: ```js 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. ```js var output = new CleanCSS(options).minify(source, inputSourceMap); ``` or a callback invoked when optimizations are finished, e.g. ```js 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. ```js 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: ```js new CleanCSS().minify(['path/to/file/one', 'path/to/file/two']); ``` ```js 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 `@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) { 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. ```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}`; * `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: * [Broccoli](https://github.com/broccolijs/broccoli#broccoli): [broccoli-clean-css](https://github.com/shinnn/broccoli-clean-css) * [Brunch](http://brunch.io/): [clean-css-brunch](https://github.com/brunch/clean-css-brunch) * [Grunt](http://gruntjs.com): [grunt-contrib-cssmin](https://github.com/gruntjs/grunt-contrib-cssmin) * [Gulp](http://gulpjs.com/): [gulp-clean-css](https://github.com/scniro/gulp-clean-css) * [Gulp](http://gulpjs.com/): [using vinyl-map as a wrapper - courtesy of @sogko](https://github.com/jakubpawlowicz/clean-css/issues/342) * [component-builder2](https://github.com/component/builder2.js): [builder-clean-css](https://github.com/poying/builder-clean-css) * [Metalsmith](http://metalsmith.io): [metalsmith-clean-css](https://github.com/aymericbeaumet/metalsmith-clean-css) * [Lasso](https://github.com/lasso-js/lasso): [lasso-clean-css](https://github.com/yomed/lasso-clean-css) * [Start](https://github.com/start-runner/start): [start-clean-css](https://github.com/start-runner/clean-css) ## 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](https://github.com/jakubpawlowicz/clean-css/blob/master/CONTRIBUTING.md). ## How to get started? First clone the sources: ```bash git clone git@github.com:jakubpawlowicz/clean-css.git ``` then install dependencies: ```bash cd clean-css npm install ``` then use any of the following commands to verify your copy: ```bash 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](https://github.com/abarre) (Anthony Barre) for improvements to `@import` processing; * [@alexlamsl](https://github.com/alexlamsl) (Alex Lam S.L.) for testing early clean-css 4 versions, reporting bugs, and suggesting numerous improvements. * [@altschuler](https://github.com/altschuler) (Simon Altschuler) for fixing `@import` processing inside comments; * [@ben-eb](https://github.com/ben-eb) (Ben Briggs) for sharing ideas about CSS optimizations; * [@facelessuser](https://github.com/facelessuser) (Isaac) for pointing out a flaw in clean-css' stateless mode; * [@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).