NPM version Linux Build Status Windows Build status Dependency Status devDependency Status

What is clean-css?

Clean-css is a fast and efficient Node.js library for minifying CSS files.

According to tests it is one of the best available.

Usage

What are the requirements?

Node.js 0.10+ (tested on CentOS, Ubuntu, OS X 10.6+, and Windows 7+) or io.js 3.0+

How to install clean-css?

npm install clean-css

How to use clean-css CLI?

Clean-css accepts the following command line arguments (please make sure you use <source-file> as the very last argument to avoid potential issues):

cleancss [options] source-file, [source-file, ...]

-h, --help                     output usage information
-v, --version                  output the version number
-b, --keep-line-breaks         Keep line breaks
-c, --compatibility [ie7|ie8]  Force compatibility mode (see Readme for advanced examples)
-d, --debug                    Shows debug information (minification time & compression efficiency)
-o, --output [output-file]     Use [output-file] as output instead of STDOUT
-r, --root [root-path]         Set a root path to which resolve absolute @import rules
-s, --skip-import              Disable @import processing
-t, --timeout [seconds]        Per connection timeout when fetching remote @imports (defaults to 5 seconds)
--rounding-precision [n]       Rounds to `N` decimal places. Defaults to 2. -1 disables rounding
--s0                           Remove all special comments, i.e. /*! comment */
--s1                           Remove all special comments but the first one
--semantic-merging             Enables unsafe mode by assuming BEM-like semantic stylesheets (warning, this may break your styling!)
--skip-advanced                Disable advanced optimizations - ruleset reordering & merging
--skip-aggressive-merging      Disable properties merging based on their order
--skip-import-from [rules]     Disable @import processing for specified rules
--skip-media-merging           Disable @media merging
--skip-rebase                  Disable URLs rebasing
--skip-restructuring           Disable restructuring optimizations
--skip-shorthand-compacting    Disable shorthand compacting
--source-map                   Enables building input's source map
--source-map-inline-sources    Enables inlining sources inside source maps

Examples:

To minify a public.css file into public-min.css do:

cleancss -o public-min.css public.css

To minify the same public.css into the standard output skip the -o parameter:

cleancss public.css

More likely you would like to concatenate a couple of files. If you are on a Unix-like system:

cat one.css two.css three.css | cleancss -o merged-and-minified.css

On Windows:

type one.css two.css three.css | cleancss -o merged-and-minified.css

Or even gzip the result at once:

cat one.css two.css three.css | cleancss | gzip -9 -c > merged-minified-and-gzipped.css.gz

How to use clean-css API?

var CleanCSS = require('clean-css');
var source = 'a{font-weight:bold;}';
var minified = new CleanCSS().minify(source).styles;

CleanCSS constructor accepts a hash as a parameter, i.e., new CleanCSS(options) with the following options available:

The output of minify method (or the 2nd argument to passed callback) is a hash containing the following fields:

How to make sure remote @imports are processed correctly?

In order to inline remote @import statements you need to provide a callback to minify method, e.g.:

var CleanCSS = require('clean-css');
var source = '@import url(http://path/to/remote/styles);';
new CleanCSS().minify(source, function (errors, minified) {
  // minified.styles
});

This is due to a fact, that, while local files can be read synchronously, remote resources can only be processed asynchronously. If you don’t provide a callback, then remote @imports will be left intact.

How to use clean-css with build tools?

What are the clean-css’ dev commands?

First clone the source, then run:

How to contribute to clean-css?

See CONTRIBUTING.md.

Tips & Tricks

How to preserve a comment block?

Use the /*! notation instead of the standard one /*:

/*!
  Important comments included in minified output.
*/

How to rebase relative image URLs?

Clean-css will handle it automatically for you (since version 1.1) in the following cases:

How to generate source maps?

Source maps are supported since version 3.0.

Additionally to mapping original CSS files, clean-css also supports input source maps, so minified styles can be mapped into their Less or Sass sources directly.

Source maps are generated using source-map module from Mozilla.

Using CLI

To generate a source map, use --source-map switch, e.g.:

cleancss --source-map --output styles.min.css styles.css

Name of the output file is required, so a map file, named by adding .map suffix to output file name, can be created (styles.min.css.map in this case).

Using API

To generate a source map, use sourceMap: true option, e.g.:

new CleanCSS({ sourceMap: true, target: pathToOutputDirectory })
  .minify(source, function (minified) {
    // access minified.sourceMap for SourceMapGenerator object
    // see https://github.com/mozilla/source-map/#sourcemapgenerator for more details
    // see https://github.com/jakubpawlowicz/clean-css/blob/master/bin/cleancss#L114 on how it's used in clean-css' CLI
});

Using API you can also pass an input source map directly:

new CleanCSS({ sourceMap: inputSourceMapAsString, target: pathToOutputDirectory })
  .minify(source, function (minified) {
    // access minified.sourceMap to access SourceMapGenerator object
    // see https://github.com/mozilla/source-map/#sourcemapgenerator for more details
    // see https://github.com/jakubpawlowicz/clean-css/blob/master/bin/cleancss#L114 on how it's used in clean-css' CLI
});

Or even multiple input source maps at once (available since version 3.1):

new CleanCSS({ sourceMap: true, target: pathToOutputDirectory }).minify({
  'path/to/source/1': {
    styles: '...styles...',
    sourceMap: '...source-map...'
  },
  'path/to/source/2': {
    styles: '...styles...',
    sourceMap: '...source-map...'
  }
}, function (minified) {
  // access minified.sourceMap as above
});

How to minify multiple files with API?

Passing an array

new CleanCSS().minify(['path/to/file/one', 'path/to/file/two']);

Passing a hash

new CleanCSS().minify({
  'path/to/file/one': {
    styles: 'contents of file one'
  },
  'path/to/file/two': {
    styles: 'contents of file two'
  }
});

How to set a compatibility mode?

Compatibility settings are controlled by --compatibility switch (CLI) and compatibility option (library mode).

In both modes the following values are allowed:

Since clean-css 3 a fine grained control is available over those settings, with the following options available:

For example, using --compatibility 'ie8,+units.rem' will ensure IE8 compatibility while enabling rem units so the following style margin:0px 0rem can be shortened to margin:0, while in pure IE8 mode it can’t be.

To pass a single off (-) switch in CLI please use the following syntax --compatibility *,-units.rem.

In library mode you can also pass compatibility as a hash of options.

What advanced optimizations are applied?

All advanced optimizations are dispatched here, and this is what they do:

Acknowledgments (sorted alphabetically)

License

Clean-css is released under the MIT License.