clean-css

clean-css is a fast and efficient CSS optimizer for [Node.js](http://nodejs.org/) platform and [any modern browser](https://clean-css.github.io/). According to [tests](http://goalsmashers.github.io/css-minification-benchmark/) it is one of the best available. __IMPORTANT: clean-css is now in a [maintenance mode](https://github.com/clean-css/clean-css/discussions/1209). PRs are still welcome, and I will try do an occasional bugfix release.__ **Table of Contents** - [Node.js version support](#nodejs-version-support) - [Install](#install) - [Use](#use) * [What's new in version 5.3](#whats-new-in-version-53) * [What's new in version 5.0](#whats-new-in-version-50) * [What's new in version 4.2](#whats-new-in-version-42) * [What's new in version 4.1](#whats-new-in-version-41) * [Important: 4.0 breaking changes](#important-40-breaking-changes) * [Constructor options](#constructor-options) * [Compatibility modes](#compatibility-modes) * [Fetch option](#fetch-option) * [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) * [Plugins](#plugins) * [Minify method](#minify-method) * [Promise interface](#promise-interface) * [CLI utility](#cli-utility) - [FAQ](#faq) * [How to optimize multiple files?](#how-to-optimize-multiple-files) * [How to process multiple files without concatenating them into one output file?](#how-to-process-multiple-files-without-concatenating-them-into-one-output-file) * [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 keep a CSS fragment intact?](#how-to-keep-a-css-fragment-intact) * [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) * [What errors and warnings are?](#what-errors-and-warnings-are) * [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 10.0+ (tested on Linux, OS X, and Windows) # Install ``` npm install --save-dev 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); ``` ## What's new in version 5.3 clean-css 5.3 introduces one new feature: * variables can be optimized using level 1's `variableValueOptimizers` option, which accepts a list of [value optimizers](https://github.com/clean-css/clean-css/blob/master/lib/optimizer/level-1/value-optimizers.js) or a list of their names, e.g. `variableValueOptimizers: ['color', 'fraction']`. ## What's new in version 5.0 clean-css 5.0 introduced some breaking changes: * Node.js 6.x and 8.x are officially no longer supported; * `transform` callback in level-1 optimizations is removed in favor of new [plugins](#plugins) interface; * changes default Internet Explorer compatibility from 10+ to >11, to revert the old default use `{ compatibility: 'ie10' }` flag; * changes default `rebase` option from `true` to `false` so URLs are not rebased by default. Please note that if you set `rebaseTo` option it still counts as setting `rebase: true` to preserve some of the backward compatibility. And on the new features side of things: * format options now accepts numerical values for all breaks, which will allow you to have more control over output formatting, e.g. `format: {breaks: {afterComment: 2}}` means clean-css will add two line breaks after each comment * a new `batch` option (defaults to `false`) is added, when set to `true` it will process all inputs, given either as an array or a hash, without concatenating them. ## 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](#how-to-apply-arbitrary-transformations-to-css-properties); * adds configurable line breaks via `format: { breakWith: 'lf' }` option. ## 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: } }` 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://clean-css.github.io/) gets an improved settings panel with "reset to defaults", instant option changes, and settings being persisted across sessions. ## 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/clean-css/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; * `fetch` - controls a function for handling remote requests; see [fetch option](#fetch-option) for examples (since 4.1.0); * `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 `false`; * `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/clean-css/clean-css/blob/master/lib/options/compatibility.js), with the following options available: ``` … ``` 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 }) ``` ## Fetch option 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/clean-css/clean-css/blob/master/lib/reader/load-remote-resource.js) logic is