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
Node.js version support
clean-css-cli requires Node.js 4.0+ (tested on Linux, OS X, and Windows)
Install
npm install clean-css-cli
Use
cleancss -o one.min.css one.css
Important: 4.0 breaking changes
clean-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;
--root
and --relativeTo
options are replaced by a single option taken from --output
path - this means that rebasing URLs and import inlining is much simpler but may not be (YMMV) as powerful as in 3.x;--rounding-precision
is disabled by default;--rounding-precision
applies to all units now, not only px
as in 3.x;--skip-import
and --skip-import-from
are merged into --inline
option which defaults to local
. Remote @import
rules are NOT inlined by default anymore;- renames
--timeout
option 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 ie9
option; - moves
--rounding-precision
, --s0
, and --s1
options to level 1 optimization options, see examples; - moves
--skip-media-merging
, --skip-restructuring
, --semantic-merging
, and --skip-shorthand-compacting
to level 2 optimizations options, see examples below; - level 1 optimizations are the new default, up to 3.x it was level 2;
--keep-breaks
option is replaced with --format keep-breaks
to ease transition;--skip-aggressive-merging
option is removed as aggressive merging is replaced by smarter override merging.
CLI options
-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)
--skip-rebase Disable URLs rebasing
--source-map Enables building input's source map
--source-map-inline-sources Enables inlining sources inside source maps
Compatibility modes
There 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.css
Formatting options
The --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`
Inlining options
--inline
option whitelists which @import
rules will be processed, e.g.
cleancss --inline local one.css # default
cleancss --inline all # same as local,remote
cleancss --inline local,mydomain.example.com one.css
cleancss --inline 'local,remote,!fonts.googleapis.com' one.css
Optimization levels
The --level
option can be either 0
, 1
(default), or 2
, e.g.
cleancss --level 2 one.css
or 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
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.css
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:
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`
# `optimizeFont controls `font` property optimizatons; defaults to `on`
# `optimizeFontWeight` controls `font-weight` property optimizatons; defaults to `on`
# `optimizeOutline` controls `outline` property optimizatons; defaults to `on`
# `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.css
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:
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`
# `restructureRules` controls rule restructuring; defaults to `off`
There is an all
shortcut for toggling all options at the same time, e.g.
cleancss -O2 all:off;removeDuplicateRules:on one.css
FAQ
More answers can be found in clean-css FAQ section.
How to optimize multiple files?
It can be done by passing in paths to multiple files, e.g.
cleancss -o merged.min.css one.css two.css three.css
How to specify a custom rounding precision?
The level 1 roundingPrecision
optimization option accept a string with per-unit rounding precision settings, e.g.
cleancss -O1 roundingPrecision:all=3,px=5
which sets all units rounding precision to 3 digits except px
unit precision of 5 digits.
How to rebase relative image URLs?
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
a {
background:url(image.png)
}
cleancss -o build/one.min.css one.css
a{background:url(../image.png)}
How to apply level 1 & 2 optimizations at the same time?
Using -O
option twice and specifying optimization options in each, e.g.
cleancss -O1 all:on,normalizeUrls:off -O2 restructureRules:on one.css
will apply level 1 optimizations, except url normalization, and default level 2 optimizations with rule restructuring.
Contributing
See CONTRIBUTING.md.
How to get started?
First clone the sources:
git clone git@github.com:jakubpawlowicz/clean-css-cli.git
then install dependencies:
cd clean-css-cli
npm install
then 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 tests
License
clean-css-cli is released under the MIT License.