clean-css

What is clean-css?

clean-css is a fast and efficient CSS optimizer for Node.js and the web. It minifies CSS by removing whitespace, comments, and unnecessary characters, merging identical rules, and applying other optimization techniques. It can be used to reduce the size of CSS files, which can lead to faster page load times and improved performance.

What are clean-css's main functionalities?

Minification

This feature allows you to minify CSS by removing unnecessary characters and whitespace, which results in smaller file sizes.

const CleanCSS = require('clean-css');
new CleanCSS().minify('a { font-weight: bold; }', function (error, output) {
  console.log(output.styles);
});

Source Map Generation

clean-css can generate source maps for the minified CSS, which is useful for debugging minified code in the browser.

const CleanCSS = require('clean-css');
new CleanCSS({ sourceMap: true, sourceMapInlineSources: true }).minify({ 'styles.css': { styles: 'a { color: #000 }' } }, function (error, output) {
  console.log(output.sourceMap.toString());
});

Merging of Identical CSS Rules

This feature merges identical CSS rules into one to reduce file size and redundancy in the code.

const CleanCSS = require('clean-css');
new CleanCSS().minify('a { color: red; } a { color: red; }', function (error, output) {
  console.log(output.styles);
});

Optimizing CSS Properties

clean-css can optimize CSS properties, such as converting hex color codes to shorter names when possible.

const CleanCSS = require('clean-css');
new CleanCSS().minify('a { color: #FF0000; }', function (error, output) {
  console.log(output.styles);
});

Other packages similar to clean-css

cssnano

cssnano is a modular CSS minifier that utilizes PostCSS. It offers optimizations like reducing calc() references, z-index rebasing, and discarding unused at-rules. Compared to clean-css, cssnano provides a plugin system and can be more configurable due to its modular nature.

uglifycss

uglifycss is a simple CSS minifier that works both in Node.js and the browser. It is less feature-rich compared to clean-css and does not support source maps, but it is straightforward to use for basic minification tasks.

csso

csso (CSS Optimizer) is a CSS minifier with structural optimizations. It can restructure CSS rules to reduce file size and also merge selectors and properties. csso is known for its aggressive optimization techniques, which sometimes can be more efficient than clean-css, but may also require careful testing to ensure the final CSS behaves as expected.

README

What is clean-css?

Clean-css is a node.js library for minifying CSS files. It does the same job as YUI Compressor's CSS minifier, but much faster thanks to many speed optimizations and node.js' V8 engine.

Usage

What are the requirements?

node.js 0.8.0+ (tested on CentOS, Ubuntu, OS X 10.6+, and Windows 7+)

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>

-h, --help                  Output usage information
-v, --version               Output the version number
-e, --remove-empty          Remove empty declarations, e.g. a{}
-b, --keep-line-breaks      Keep line breaks
--s0                        Remove all special comments, i.e. /*! comment */
--s1                        Remove all special comments but the first one
-r, --root [root-path]      A root path to which resolve absolute @import rules and rebase relative URLs
-o, --output [output-file]  Use [output-file] as output instead of STDOUT
-s, --skip-import           Disable @import processing
--skip-rebase               Disable URLs rebasing
-d, --debug                 Shows debug information (minification time & compression efficiency)

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 programmatically?

var cleanCSS = require('clean-css');
var source = 'a{font-weight:bold;}';
var minimized = cleanCSS.process(source);

Process method accepts a hash as a second parameter, i.e., cleanCSS.process(source, options) with the following options available:

• keepSpecialComments - * for keeping all (default), 1 for keeping first one, 0 for removing all
• keepBreaks - whether to keep line breaks (default is false)
• removeEmpty - whether to remove empty elements (default is false)
• benchmark - turns on benchmarking mode measuring time spent on cleaning up (run npm run bench to see example)
• root - path to resolve absolute @import rules and rebase relative URLs
• relativeTo - path with which to resolve relative @import rules and URLs
• processImport - whether to process @import rules
• noRebase - whether to skip URLs rebasing

What are the clean-css' dev commands?

First clone the source, then run:

• npm run bench for clean-css benchmarks (see test/bench.js for details)
• npm run check to check JS sources with JSHint
• npm test for the test suite

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:

• When using the CLI:
  1. Use an output path via -o/--output to rebase URLs as relative to the output file.
  2. Use a root path via -r/--root to rebase URLs as absolute from the given root path.
  3. If you specify both then -r/--root takes precendence.
• When using clean-css as a library:
  1. Use a combination of relativeTo and target options for relative rebase (same as 1 in CLI).
  2. Use a combination of relativeTo and root options for absolute rebase (same as 2 in CLI).
  3. root takes precendence over target as in CLI.

Acknowledgments

• Vincent Voyer (@vvo) for a patch with better empty element regex and for inspiring us to do many performance improvements in 0.4 release.
• Isaac (@facelessuser) for pointing out a flaw in clean-css' stateless mode.
• Jan Michael Alonzo (@jmalonzo) for a patch removing node.js' old sys package.
• @XhmikosR for suggesting new features (option to remove special comments and strip out URLs quotation) and pointing out numerous improvements (JSHint, media queries).
• Anthony Barre (@abarre) for improvements to @import processing, namely introducing the --skip-import / processImport options.

License

Clean-css is released under the MIT License.