clean-css-cli is a command-line interface to clean-css - fast and efficient CSS optimizer for Node.js.
Previously a part of clean-css it's a separate package since clean-css 4.0.
Table of Contents
clean-css-cli requires Node.js 4.0+ (tested on Linux, OS X, and Windows)
npm install clean-css-cli -gNote: Global install via -g option is recommended unless you want to execute the binary via a relative path, i.e. ./node_modules/.bin/cleancss
cleancss -o one.min.css one.cssclean-css-cli 4.0 introduces some breaking changes:
- API and CLI interfaces are split, so CLI has been moved to this repository while API stays at clean-css;
--rootand--relativeTooptions are replaced by a single option taken from--outputpath - this means that rebasing URLs and import inlining is much simpler but may not be (YMMV) as powerful as in 3.x;--rounding-precisionis disabled by default;--rounding-precisionapplies to all units now, not onlypxas in 3.x;--skip-importand--skip-import-fromare merged into--inlineoption which defaults tolocal. Remote@importrules are NOT inlined by default anymore;- renames
--timeoutoption to--inline-timeout; - 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 ie9option; - moves
--rounding-precision,--s0, and--s1options to level 1 optimization options, see examples; - moves
--skip-media-merging,--skip-restructuring,--semantic-merging, and--skip-shorthand-compactingto level 2 optimizations options, see examples below; - level 1 optimizations are the new default, up to 3.x it was level 2;
--keep-breaksoption is replaced with--format keep-breaksto ease transition;--skip-aggressive-mergingoption is removed as aggressive merging is replaced by smarter override merging.
clean-css-cli 4.1 introduces the following changes / features:
- clean-css 4.1 as a dependency;
--remove-inlined-filesoption for removing files inlined in <source-file ...> or via@importstatements;- adds glob pattern matching to source paths, see example;
- allows non-boolean compatibility options, e.g.
--compatibility selectors.mergeLimit=512; - extracts CLI into an importable module, so it can be reused and enhanced if needed;
- adds
beforeMinifycallback as a second argument to CLI module, see example use case.
-h, --help output usage information
-v, --version output the version number
-c, --compatibility [ie7|ie8] Force compatibility mode (see Readme for advanced examples)
-d, --debug Shows debug information (minification time & compression efficiency)
-f, --format <options> Controls output formatting, see examples below
-o, --output [output-file] Use [output-file] as output instead of STDOUT
-O <n> [optimizations] Turn on level <n> optimizations; optionally accepts a list of fine-grained options, defaults to `1`, see examples below
--inline [rules] Enables inlining for listed sources (defaults to `local`)
--inline-timeout [seconds] Per connection timeout when fetching remote stylesheets (defaults to 5 seconds)
--remove-inlined-files Remove files inlined in <source-file ...> or via `@import` statements
--skip-rebase Disable URLs rebasing
--source-map Enables building input's source map
--source-map-inline-sources Enables inlining sources inside source mapsThere is a certain number of compatibility mode shortcuts, namely:
--compatibility '*'(default) - Internet Explorer 10+ compatibility mode--compatibility ie9- Internet Explorer 9+ compatibility mode--compatibility ie8- Internet Explorer 8+ compatibility mode--compatibility ie7- Internet Explorer 7+ compatibility mode
Each of these modes is an alias to a fine grained configuration, with the following options available:
cleancss --compatibility '*,-properties.urlQuotes'
cleancss --compatibility '*,+properties.ieBangHack,+properties.ieFilters'
# [+-]colors.opacity controls `rgba()` / `hsla()` color support; defaults to `on` (+)
# [+-]properties.backgroundClipMerging controls background-clip merging into shorthand; defaults to `on` (+)
# [+-]properties.backgroundOriginMerging controls background-origin merging into shorthand; defaults to `on` (+)
# [+-]properties.backgroundSizeMerging controls background-size merging into shorthand; defaults to `on` (+)
# [+-]properties.colors controls color optimizations; defaults to `on` (+)
# [+-]properties.ieBangHack controls keeping IE bang hack; defaults to `off` (-)
# [+-]properties.ieFilters controls keeping IE `filter` / `-ms-filter`; defaults to `off` (-)
# [+-]properties.iePrefixHack controls keeping IE prefix hack; defaults to `off` (-)
# [+-]properties.ieSuffixHack controls keeping IE suffix hack; defaults to `off` (-)
# [+-]properties.merging controls property merging based on understandability; defaults to `on` (+)
# [+-]properties.shorterLengthUnits controls shortening pixel units into `pc`, `pt`, or `in` units; defaults to `off` (-)
# [+-]properties.spaceAfterClosingBrace controls keeping space after closing brace - `url() no-repeat` cleancss --compatibility '*,into `url('roperties.no-repeat`; defaults to `on` (+)
# [+-]properties.urlQuotes controls keeping quoting inside `url()`; defaults to `off` (-)
# [+-]properties.zeroUnitsf units `0` value; defaults to `on` (+)
# [+-]selectors.adjacentSpace controls extra space before `nav` element; defaults to `off` (-)
# [+-]selectors.ie7Hack controls removal of IE7 selector hacks, e.g. `*+html...`; defaults to `on` (+)
# [+-]units.ch controls treating `ch` as a supported unit; defaults to `on` (+)
# [+-]units.in controls treating `in` as a supported unit; defaults to `on` (+)
# [+-]units.pc controls treating `pc` as a supported unit; defaults to `on` (+)
# [+-]units.pt controls treating `pt` as a supported unit; defaults to `on` (+)
# [+-]units.rem controls treating `rem` as a supported unit; defaults to `on` (+)
# [+-]units.vh controls treating `vh` as a supported unit; defaults to `on` (+)
# [+-]units.vm controls treating `vm` as a supported unit; defaults to `on` (+)
# [+-]units.vmax controls treating `vmax` as a supported unit; defaults to `on` (+)
# [+-]units.vmin controls treating `vmin` as a supported unit; defaults to `on` (+)You can also chain more rules after a shortcut when setting a compatibility:
cleancss --compatibility 'ie9,-colors.opacity,-units.rem' one.cssThe --format option accept the following options:
cleancss --format beautify one.css
cleancss --format keep-breaks one.css
cleancss --format 'indentBy:1;indentWith:tab' one.css
cleancss --format 'breaks:afterBlockBegins=on;spaces:aroundSelectorRelation=on' one.css
# `breaks` controls where to insert breaks
# `afterAtRule` controls if a line break comes after an at-rule; e.g. `@charset`; defaults to `off` (alias to `false`)
# `afterBlockBegins` controls if a line break comes after a block begins; e.g. `@media`; defaults to `off`
# `afterBlockEnds` controls if a line break comes after a block ends, defaults to `off`
# `afterComment` controls if a line break comes after a comment; defaults to `off`
# `afterProperty` controls if a line break comes after a property; defaults to `off`
# `afterRuleBegins` controls if a line break comes after a rule begins; defaults to `off`
# `afterRuleEnds` controls if a line break comes after a rule ends; defaults to `off`
# `beforeBlockEnds` controls if a line break comes before a block ends; defaults to `off`
# `betweenSelectors` controls if a line break comes between selectors; defaults to `off`
# `indentBy` controls number of characters to indent with; defaults to `0`
# `indentWith` controls a character to indent with, can be `space` or `tab`; defaults to `space`
# `spaces` controls where to insert spaces
# `aroundSelectorRelation` controls if spaces come around selector relations; e.g. `div > a`; defaults to `off`
# `beforeBlockBegins` controls if a space comes before a block begins; e.g. `.block {`; defaults to `off`
# `beforeValue` controls if a space comes before a value; e.g. `width: 1rem`; defaults to `off`
# `wrapAt` controls maximum line length; defaults to `off`--inline option whitelists which @import rules will be processed, e.g.
cleancss --inline local one.css # defaultcleancss --inline all # same as local,remotecleancss --inline local,mydomain.example.com one.csscleancss --inline 'local,remote,!fonts.googleapis.com' one.cssThe --level option can be either 0, 1 (default), or 2, e.g.
cleancss --level 2 one.cssor a fine-grained configuration given via a string.
Please note that level 1 optimization options are generally safe while level 2 optimizations should be safe for most users.
Level 0 optimizations simply means "no optimizations". Use it when you'd like to inline imports and / or rebase URLs but skip everything else, e.g.
cleancss -O0 one.cssLevel 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:
cleancss -O1 one.css
cleancss -O1 removeQuotes:off;roundingPrecision:4;specialComments:1 one.css
# `cleanupCharsets` controls `@charset` moving to the front of a stylesheet; defaults to `on`
# `normalizeUrls` controls URL normalzation; default to `on`
# `optimizeBackground` controls `background` property optimizatons; defaults to `on`
# `optimizeBorderRadius` controls `border-radius` property optimizatons; defaults to `on`
# `optimizeFilter` controls `filter` property optimizatons; defaults to `on`
# `optimizeFontWeight` controls `font-weight` property optimizatons; defaults to `on`
# `optimizeOutline` controls `outline` property optimizatons; defaults to `on`
# `removeEmpty` controls removing empty rules and nested blocks; defaults to `on` (since 4.1.0)
# `removeNegativePaddings` controls removing negative paddings; defaults to `on`
# `removeQuotes` controls removing quotes when unnecessary; defaults to `on`
# `removeWhitespace` controls removing unused whitespace; defaults to `on`
# `replaceMultipleZeros` contols removing redundant zeros; defaults to `on`
# `replaceTimeUnits` controls replacing time units with shorter values; defaults to `on
# `replaceZeroUnits` controls replacing zero values with units; defaults to `on`
# `roundingPrecision` rounds pixel values to `N` decimal places; `off` disables rounding; defaults to `off`
# `selectorsSortingMethod` denotes selector sorting method; can be `natural` or `standard`; defaults to `standard`
# `specialComments` denotes a number of /*! ... */ comments preserved; defaults to `all`
# `tidyAtRules` controls at-rules (e.g. `@charset`, `@import`) optimizing; defaults to `on`
# `tidyBlockScopes` controls block scopes (e.g. `@media`) optimizing; defaults to `on`
# `tidySelectors` controls selectors optimizing; defaults to `on`There is an all shortcut for toggling all options at the same time, e.g.
cleancss -O1 'all:off;tidySelectors:on' one.cssLevel 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:
cleancss -O2 one.css
cleancss -O2 mergeMedia:off;restructureRules:off;mergeSemantically:on;mergeIntoShorthands:off one.css
# `mergeAdjacentRules` controls adjacent rules merging; defaults to `on`
# `mergeIntoShorthands` controls merging properties into shorthands; defaults to `on`
# `mergeMedia` controls `@media` merging; defaults to `on`
# `mergeNonAdjacentRules` controls non-adjacent rule merging; defaults to `on`
# `mergeSemantically` controls semantic merging; defaults to `off`
# `overrideProperties` controls property overriding based on understandability; defaults to `on`
# `reduceNonAdjacentRules` controls non-adjacent rule reducing; defaults to `on`
# `removeDuplicateFontRules` controls duplicate `@font-face` removing; defaults to `on`
# `removeDuplicateMediaBlocks` controls duplicate `@media` removing; defaults to `on`
# `removeDuplicateRules` controls duplicate rules removing; defaults to `on`
# `removeEmpty` controls removing empty rules and nested blocks; defaults to `on` (since 4.1.0)
# `removeUnusedAtRules` controls unused at rule removing; defaults to `off` (since 4.1.0)
# `restructureRules` controls rule restructuring; defaults to `off`
# `skipProperties` controls which properties won\'t be optimized, defaults to empty list which means all will be optimized (since 4.1.0)There is an all shortcut for toggling all options at the same time, e.g.
cleancss -O2 'all:off;removeDuplicateRules:on' one.cssclean-css-cli can also be used as a module in a way of enhancing its functionality in a programmatic way, e.g.
#!/usr/bin/env node
var cleanCssCli = require('clean-css-cli');
return cleanCssCli(process, function beforeMinify(cleanCss) {
cleanCss.options.level['1'].transform = function (propertyName, propertyValue) {
if (propertyName == 'background-image' && propertyValue.indexOf('../valid/path/to') == -1) {
return propertyValue.replace('url(', 'url(../valid/path/to/');
}
}
});More answers can be found in clean-css FAQ section.
It can be done by passing in paths to multiple files, e.g.
cleancss -o merged.min.css one.css two.css three.cssSince version 4.1.0 it can also be done using glob pattern matching, e.g.
cleancss -o merged.min.css *.cssThe level 1 roundingPrecision optimization option accept a string with per-unit rounding precision settings, e.g.
cleancss -O1 roundingPrecision:all=3,px=5which sets all units rounding precision to 3 digits except px unit precision of 5 digits.
clean-css-cli will handle it automatically for you when full paths to input files are passed in and --output option is used, e.g
/*! one.css */
a {
background:url(image.png)
}cleancss -o build/one.min.css one.css/*! build/one.min.css */
a{background:url(../image.png)}Using -O option twice and specifying optimization options in each, e.g.
cleancss -O1 all:on,normalizeUrls:off -O2 restructureRules:on one.csswill apply level 1 optimizations, except url normalization, and default level 2 optimizations with rule restructuring.
See CONTRIBUTING.md.
First clone the sources:
git clone git@github.com:jakubpawlowicz/clean-css-cli.gitthen install dependencies:
cd clean-css-cli
npm installthen use any of the following commands to verify your copy:
npm run check # to lint JS sources with [JSHint](https://github.com/jshint/jshint/)
npm test # to run all testsclean-css-cli is released under the MIT License.