wallet-core/node_modules/clean-css/README.md

clean-css is a fast and efficient CSS optimizer for Node.js platform and any modern browser.

According to tests it is one of the best available.

Table of Contents

• Node.js version support
• Install
• Use
  • Important: 4.0 breaking changes
  • Constructor options
  • Compatibility modes
  • Formatting options
  • Inlining options
  • Optimization levels
    • Level 0 optimizations
    • Level 1 optimizations
    • Level 2 optimizations
  • Minify method
  • Promise interface
• FAQ
  • How to optimize multiple files?
  • How to process remote @imports correctly?
  • How to apply arbitrary transformations to CSS properties?
  • How to specify a custom rounding precision?
  • How to preserve a comment block?
  • How to rebase relative image URLs?
  • How to work with source maps?
  • How to apply level 1 & 2 optimizations at the same time?
  • What level 2 optimizations do?
  • How to use clean-css with build tools?
  • How to use clean-css from web browser?
• Contributing
  • How to get started?
• Acknowledgments
• License

Node.js version support

clean-css requires Node.js 4.0+ (tested on Linux, OS X, and Windows)

Install

npm install clean-css

Use

var CleanCSS = require('clean-css');
var input = 'a{font-weight:bold;}';
var options = { /* options */ };
var output = new CleanCSS(options).minify(input);

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;
• 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 for examples;
• format - controls output CSS formatting; defaults to false; see formatting options for examples;
• inline - controls @import inlining rules; defaults to 'local'; see inlining options for examples;
• inlineRequest - controls extra options for inlining remote @import rules, can be any of HTTP(S) request options;
• 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 for examples;
• rebase - controls URL rebasing; defaults to true;
• 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 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, with the following options available:

new CleanCSS({
  compatibility: {
    colors: {
      opacity: true // controls `rgba()` / `hsla()` color support
    },
    properties: {
      backgroundClipMerging: true, // controls background-clip merging into shorthand
      backgroundOriginMerging: true, // controls background-origin merging into shorthand
      backgroundSizeMerging: true, // controls background-size merging into shorthand
      colors: true, // controls color optimizations
      ieBangHack: false, // controls keeping IE bang hack
      ieFilters: false, // controls keeping IE `filter` / `-ms-filter`
      iePrefixHack: false, // controls keeping IE prefix hack
      ieSuffixHack: false, // controls keeping IE suffix hack
      merging: true, // controls property merging based on understandability
      shorterLengthUnits: false, // controls shortening pixel units into `pc`, `pt`, or `in` units
      spaceAfterClosingBrace: true, // controls keeping space after closing brace - `url() no-repeat` into `url()no-repeat`
      urlQuotes: false, // controls keeping quoting inside `url()`
      zeroUnits: true // controls removal of units `0` value
    },
    selectors: {
      adjacentSpace: false, // controls extra space before `nav` element
      ie7Hack: true, // controls removal of IE7 selector hacks, e.g. `*+html...`
      mergeablePseudoClasses: [':active', ...], // controls a whitelist of mergeable pseudo classes
      mergeablePseudoElements: ['::after', ...] // controls a whitelist of mergeable pseudo elements
    },
    units: {
      ch: true, // controls treating `ch` as a supported unit
      in: true, // controls treating `in` as a supported unit
      pc: true, // controls treating `pc` as a supported unit
      pt: true, // controls treating `pt` as a supported unit
      rem: true, // controls treating `rem` as a supported unit
      vh: true, // controls treating `vh` as a supported unit
      vm: true, // controls treating `vm` as a supported unit
      vmax: true, // controls treating `vmax` as a supported unit
      vmin: true // controls treating `vmin` as a supported unit
    }
  }
})

You can also use a string when setting a compatibility mode, e.g.

new CleanCSS({
  compatibility: 'ie9,-properties.merging' // sets compatibility to IE9 mode with disabled property merging
})

Formatting options

The format option accept the following options:

new CleanCSS({
  format: {
    breaks: { // controls where to insert breaks
      afterAtRule: false, // controls if a line break comes after an at-rule; e.g. `@charset`; defaults to `false`
      afterBlockBegins: false, // controls if a line break comes after a block begins; e.g. `@media`; defaults to `false`
      afterBlockEnds: false, // controls if a line break comes after a block ends, defaults to `false`
      afterComment: false, // controls if a line break comes after a comment; defaults to `false`
      afterProperty: false, // controls if a line break comes after a property; defaults to `false`
      afterRuleBegins: false, // controls if a line break comes after a rule begins; defaults to `false`
      afterRuleEnds: false, // controls if a line break comes after a rule ends; defaults to `false`
      beforeBlockEnds: false, // controls if a line break comes before a block ends; defaults to `false`
      betweenSelectors: false // controls if a line break comes between selectors; defaults to `false`
    },
    indentBy: 0, // controls number of characters to indent with; defaults to `0`
    indentWith: 'space', // controls a character to indent with, can be `'space'` or `'tab'`; defaults to `'space'`
    spaces: { // controls where to insert spaces
      aroundSelectorRelation: false, // controls if spaces come around selector relations; e.g. `div > a`; defaults to `false`
      beforeBlockBegins: false, // controls if a space comes before a block begins; e.g. `.block {`; defaults to `false`
      beforeValue: false // controls if a space comes before a value; e.g. `width: 1rem`; defaults to `false`
    },
    wrapAt: false // controls maximum line length; defaults to `false`
  }
})

Inlining options

inline option whitelists which @import rules will be processed, e.g.

new CleanCSS({
  inline: ['local'] // default
})

new CleanCSS({
  inline: ['all'] // same as ['local', 'remote']
})

new CleanCSS({
  inline: ['local', 'mydomain.example.com']
})

new CleanCSS({
  inline: ['local', 'remote', '!fonts.googleapis.com']
})

Optimization levels

The level option can be either 0, 1 (default), or 2, e.g.

new CleanCSS({
  level: 2
})

or a fine-grained configuration given via a hash.

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.

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:

new CleanCSS({
  level: {
    1: {
      cleanupCharsets: true, // controls `@charset` moving to the front of a stylesheet; defaults to `true`
      normalizeUrls: true, // controls URL normalization; defaults to `true`
      optimizeBackground: true, // controls `background` property optimizatons; defaults to `true`
      optimizeBorderRadius: true, // controls `border-radius` property optimizatons; defaults to `true`
      optimizeFilter: true, // controls `filter` property optimizatons; defaults to `true`
      optimizeFont: true, // ontrols `font` property optimizatons; defaults to `true`
      optimizeFontWeight: true, // controls `font-weight` property optimizatons; defaults to `true`
      optimizeOutline: true, // controls `outline` property optimizatons; defaults to `true`
      removeNegativePaddings: true, // controls removing negative paddings; defaults to `true`
      removeQuotes: true, // controls removing quotes when unnecessary; defaults to `true`
      removeWhitespace: true, // controls removing unused whitespace; defaults to `true`
      replaceMultipleZeros: true, // contols removing redundant zeros; defaults to `true`
      replaceTimeUnits: true, // controls replacing time units with shorter values; defaults to `true`
      replaceZeroUnits: true, // controls replacing zero values with units; defaults to `true`
      roundingPrecision: false, // rounds pixel values to `N` decimal places; `false` disables rounding; defaults to `false`
      selectorsSortingMethod: 'standard', // denotes selector sorting method; can be `natural` or `standard`; defaults to `standard`
      specialComments: 'all', // denotes a number of /*! ... */ comments preserved; defaults to `all`
      tidyAtRules: true, // controls at-rules (e.g. `@charset`, `@import`) optimizing; defaults to `true`
      tidyBlockScopes: true, // controls block scopes (e.g. `@media`) optimizing; defaults to `true`
      tidySelectors: true, // controls selectors optimizing; defaults to `true`,
      transform: function () {} // defines a callback for fine-grained property optimization; defaults to no-op
    }
  }
});

There is an all shortcut for toggling all options at the same time, e.g.

new CleanCSS({
  level: {
    1: {
      all: false, // set all values to `false`
      tidySelectors: true // turns on optimizing selectors
    }
  }
});

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:

new CleanCSS({
  level: {
    2: {
      mergeAdjacentRules: true, // controls adjacent rules merging; defaults to true
      mergeIntoShorthands: true, // controls merging properties into shorthands; defaults to true
      mergeMedia: true, // controls `@media` merging; defaults to true
      mergeNonAdjacentRules: true, // controls non-adjacent rule merging; defaults to true
      mergeSemantically: false, // controls semantic merging; defaults to false
      overrideProperties: true, // controls property overriding based on understandability; defaults to true
      reduceNonAdjacentRules: true, // controls non-adjacent rule reducing; defaults to true
      removeDuplicateFontRules: true, // controls duplicate `@font-face` removing; defaults to true
      removeDuplicateMediaBlocks: true, // controls duplicate `@media` removing; defaults to true
      removeDuplicateRules: true, // controls duplicate rules removing; defaults to true
      restructureRules: false // controls rule restructuring; defaults to false
    }
  }
});

There is an all shortcut for toggling all options at the same time, e.g.

new CleanCSS({
  level: {
    2: {
      all: false, // sets all values to `false`
      removeDuplicateRules: true // turns on removing duplicate rules
    }
  }
});

Minify method

Once configured clean-css provides a minify method to optimize a given CSS, e.g.

var output = new CleanCSS(options).minify(source);

The output of the minify method is a hash with following fields:

console.log(output.styles); // optimized output CSS as a string
console.log(output.sourceMap); // output source map if requested with `sourceMap` option
console.log(output.errors); // a list of errors raised
console.log(output.warnings); // a list of warnings raised
console.log(output.stats.originalSize); // original content size after import inlining
console.log(output.stats.minifiedSize); // optimized content size
console.log(output.stats.timeSpent); // time spent on optimizations in milliseconds
console.log(output.stats.efficiency); // a ratio of output size to input size (e.g. 25% if content was reduced from 100 bytes to 75 bytes)

The minify method also accepts an input source map, e.g.

var output = new CleanCSS(options).minify(source, inputSourceMap);

or a callback invoked when optimizations are finished, e.g.

new CleanCSS(options).minify(source, function (error, output) {
  // `output` is the same as in the synchronous call above
});

Promise interface

If you prefer clean-css to return a Promise object then you need to explicitely ask for it, e.g.

new CleanCSS({ returnPromise: true })
  .minify(source)
  .then(function (output) { console.log(output.styles); })
  .catch(function (error) { // deal with errors });

FAQ

How to optimize multiple files?

It can be done either by passing an array of paths, or, when sources are already available, a hash:

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

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

Important note - any @import rules already present in the hash will be resolved in memory.

How to process remote @imports correctly?

In order to inline remote @import statements you need to provide a callback to minify method as fetching remote assets is an asynchronous operation, e.g.:

var source = '@import url(http://example.com/path/to/remote/styles);';
new CleanCSS({ inline: ['remote'] }).minify(source, function (error, output) {
  // output.styles
});

If you don't provide a callback, then remote @imports will be left as is.

How to apply arbitrary transformations to CSS properties?

If clean-css doesn't perform a particular property optimization, you can use transform callback to apply it:

var source = '.block{background-image:url(/path/to/image.png)}';
var output = new CleanCSS({
  level: {
    1: {
      transform: function (propertyName, propertyValue) {
        if (propertyName == 'background-image' && propertyValue.indexOf('/path/to') > -1) {
          return propertyValue.replace('/path/to', '../valid/path/to');
        }
      }
    }
  }
}).minify(source);

console.log(output.styles); # => .block{background-image:url(../valid/path/to/image.png)}

Note: returning false from transform callback will drop a property.

How to specify a custom rounding precision?

The level 1 roundingPrecision optimization option accept a string with per-unit rounding precision settings, e.g.

new CleanCSS({
  level: {
    1: {
      roundingPrecision: 'all=3,px=5'
    }
  }
}).minify(source)

which sets all units rounding precision to 3 digits except px unit precision of 5 digits.

How to preserve a comment block?

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

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

How to rebase relative image URLs?

clean-css will handle it automatically for you in the following cases:

• when full paths to input files are passed in as options;
• when correct paths are passed in via a hash;
• when rebaseTo is used with any of above two.

How to work with source maps?

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

new CleanCSS({ sourceMap: true, rebaseTo: pathToOutputDirectory })
  .minify(source, function (error, output) {
    // access output.sourceMap for SourceMapGenerator object
    // see https://github.com/mozilla/source-map/#sourcemapgenerator for more details
});

You can also pass an input source map directly as a 2nd argument to minify method:

new CleanCSS({ sourceMap: true, rebaseTo: pathToOutputDirectory })
  .minify(source, inputSourceMap, function (error, output) {
    // access output.sourceMap to access SourceMapGenerator object
    // see https://github.com/mozilla/source-map/#sourcemapgenerator for more details
});

or even multiple input source maps at once:

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

How to apply level 1 & 2 optimizations at the same time?

Using the hash configuration specifying both optimization levels, e.g.

new CleanCSS({
  level: {
    1: {
      all: true,
      normalizeUrls: false
    },
    2: {
      restructureRules: true
    }
  }
})

will apply level 1 optimizations, except url normalization, and default level 2 optimizations with rule restructuring.

What level 2 optimizations do?

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

• recursivelyOptimizeBlocks - does all the following operations on a nested block, like @media or @keyframe;
• recursivelyOptimizeProperties - optimizes properties in rulesets and flat at-rules, like @font-face, by splitting them into components (e.g. margin into margin-(bottom|left|right|top)), optimizing, and restoring them back. You may want to use mergeIntoShorthands option to control whether you want to turn multiple components into shorthands;
• removeDuplicates - gets rid of duplicate rulesets with exactly the same set of properties, e.g. when including a Sass / Less partial twice for no good reason;
• mergeAdjacent - merges adjacent rulesets with the same selector or rules;
• reduceNonAdjacent - identifies which properties are overridden in same-selector non-adjacent rulesets, and removes them;
• mergeNonAdjacentBySelector - identifies same-selector non-adjacent rulesets which can be moved (!) to be merged, requires all intermediate rulesets to not redefine the moved properties, or if redefined to have the same value;
• mergeNonAdjacentByBody - same as the one above but for same-selector non-adjacent rulesets;
• restructure - tries to reorganize different-selector different-rules rulesets so they take less space, e.g. .one{padding:0}.two{margin:0}.one{margin-bottom:3px} into .two{margin:0}.one{padding:0;margin-bottom:3px};
• removeDuplicateFontAtRules - removes duplicated @font-face rules;
• removeDuplicateMediaQueries - removes duplicated @media nested blocks;
• mergeMediaQueries - merges non-adjacent @media at-rules by the same rules as mergeNonAdjacentBy* above;

How to use clean-css with build tools?

There is a number of 3rd party plugins to popular build tools:

• Broccoli: broccoli-clean-css
• Brunch: clean-css-brunch
• Grunt: grunt-contrib-cssmin
• Gulp: gulp-clean-css
• Gulp: using vinyl-map as a wrapper - courtesy of @sogko
• component-builder2: builder-clean-css
• Metalsmith: metalsmith-clean-css
• Lasso: lasso-clean-css
• Start: start-clean-css

How to use clean-css from web browser?

• https://jakubpawlowicz.github.io/clean-css/ (official web interface)
• http://refresh-sf.com/
• http://adamburgess.github.io/clean-css-online/

Contributing

See CONTRIBUTING.md.

How to get started?

First clone the sources:

git clone git@github.com:jakubpawlowicz/clean-css.git

then install dependencies:

cd clean-css
npm install

then use any of the following commands to verify your copy:

npm run bench # for clean-css benchmarks (see [test/bench.js](https://github.com/jakubpawlowicz/clean-css/blob/master/test/bench.js) for details)
npm run browserify # to create the browser-ready clean-css version
npm run check # to lint JS sources with [JSHint](https://github.com/jshint/jshint/)
npm test # to run all tests

Acknowledgments

Sorted alphabetically by GitHub handle:

• @abarre (Anthony Barre) for improvements to @import processing;
• @alexlamsl (Alex Lam S.L.) for testing early clean-css 4 versions, reporting bugs, and suggesting numerous improvements.
• @altschuler (Simon Altschuler) for fixing @import processing inside comments;
• @ben-eb (Ben Briggs) for sharing ideas about CSS optimizations;
• @facelessuser (Isaac) for pointing out a flaw in clean-css' stateless mode;
• @jmalonzo (Jan Michael Alonzo) for a patch removing node.js' old sys package;
• @lukeapage (Luke Page) for suggestions and testing the source maps feature; Plus everyone else involved in #125 for pushing it forward;
• @madwizard-thomas for sharing ideas about @import inlining and URL rebasing.
• @ngyikp (Ng Yik Phang) for testing early clean-css 4 versions, reporting bugs, and suggesting numerous improvements.
• @wagenet (Peter Wagenet) for suggesting improvements to @import inlining behavior;
• @venemo (Timur Kristóf) for an outstanding contribution of advanced property optimizer for 2.2 release;
• @vvo (Vincent Voyer) for a patch with better empty element regex and for inspiring us to do many performance improvements in 0.4 release;
• @xhmikosr for suggesting new features, like option to remove special comments and strip out URLs quotation, and pointing out numerous improvements like JSHint, media queries, etc.

License

clean-css is released under the MIT License.