csso

What is csso?

CSSO (CSS Optimizer) is a CSS minifier. It performs three kinds of optimizations: structural optimizations, reducing CSS size by merging blocks with identical properties, removing overridden properties, etc.; cleaning (removing unused @media rules, cutting out the comments, etc.); and compressing (transforming values to shorter forms, merging identical selectors, etc.). It can be used as a command-line tool or as a library.

What are csso's main functionalities?

Minification

Minifies CSS by removing whitespace, comments, and making other optimizations to reduce file size.

const csso = require('csso');
const minifiedCss = csso.minify('.test { color: #ff0000; }').css;

Structural Optimization

Optimizes CSS structure by merging blocks with identical properties and removing overridden properties.

const csso = require('csso');
const optimizedCss = csso.minify('.test { color: red; } .test { font-size: 16px; }', { restructure: true }).css;

Source Map Generation

Generates a source map that can be used to debug the minified CSS by mapping it back to the original sources.

const csso = require('csso');
const result = csso.minify('.test { color: red; }', { sourceMap: true });
const minifiedCss = result.css;
const map = result.map.toString();

Other packages similar to csso

clean-css

clean-css is a fast and efficient CSS optimizer for Node.js and the Web. It provides similar minification capabilities as CSSO but also offers advanced optimizations like restructuring.

uglifycss

uglifycss is a CSS minifier that aims to be fast and simple. It doesn't have as many features as CSSO, focusing mainly on removing whitespace and comments to compress CSS files.

purifycss

purifycss is a tool to remove unused CSS. Unlike CSSO, which focuses on optimizing existing CSS, purifycss analyzes your content and CSS files to remove unused selectors.

README

CSSO (CSS Optimizer) is a CSS minifier. It performs three sort of transformations: cleaning (removing redundant), compression (replacement for shorter form) and restructuring (merge of declarations, rulesets and so on). As a result your CSS becomes much smaller.

Usage

npm install -g csso

Or try out CSSO right in your browser (web interface).

Runners

• Gulp: gulp-csso
• Grunt: grunt-csso
• Broccoli: broccoli-csso
• PostCSS: postcss-csso

Command line

csso [input] [output] [options]

Options:

      --debug [level]       Output intermediate state of CSS during compression
  -h, --help                Output usage information
  -i, --input <filename>    Input file
      --input-map <source>  Input source map: none, auto (default) or <filename>
  -m, --map <destination>   Generate source map: none (default), inline, file or <filename>
  -o, --output <filename>   Output file (result outputs to stdout if not set)
      --restructure-off     Turns structure minimization off
      --stat                Output statistics in stderr
  -u, --usage <filenane>    Usage data file
  -v, --version             Output version

Some examples:

> csso in.css out.css

> csso in.css
...output result in stdout...

> echo '.test { color: #ff0000; }' | csso
.test{color:red}

> cat source1.css source2.css | csso | gzip -9 -c > production.css.gz

> echo '.test { color: #ff0000 }' | csso --stat >/dev/null
File:       <stdin>
Original:   25 bytes
Compressed: 16 bytes (64.00%)
Saving:     9 bytes (36.00%)
Time:       12 ms
Memory:     0.346 MB

Source maps

Source map doesn't generate by default. To generate map use --map CLI option, that can be:

• none (default) – don't generate source map
• inline – add source map into result CSS (via /*# sourceMappingURL=application/json;base64,... */)
• file – write source map into file with same name as output file, but with .map extension (in this case --output option is required)
• any other values treat as filename for generated source map

Examples:

> csso my.css --map inline
> csso my.css --output my.min.css --map file
> csso my.css --output my.min.css --map maps/my.min.map

Use --input-map option to specify input source map if needed. Possible values for option:

• auto (default) - attempt to fetch input source map by follow steps:
  • try to fetch inline map from input
  • try to fetch source map filename from input and read its content
  • (when --input is specified) check file with same name as input file but with .map extension exists and read its content
• none - don't use input source map; actually it's using to disable auto-fetching
• any other values treat as filename for input source map

Generally you shouldn't care about input source map since defaults behaviour (auto) covers most use cases.

NOTE: Input source map is using only if output source map is generating.

Usage data

CSSO can use data about how CSS is using for better compression. File with this data (JSON format) can be set using --usage option. Usage data may contain follow sections:

• tags – white list of tags
• ids – white list of ids
• classes – white list of classes
• scopes – groups of classes which never used with classes from other groups on single element

All sections are optional. Value of tags, ids and classes should be array of strings, value of scopes should be an array of arrays of strings. Other values are ignoring.

Selector filtering

tags, ids and classes are using on clean stage to filter selectors that contains something that not in list. Selectors are filtering only by those kind of simple selector which white list is specified. For example, if only tags list is specified then type selectors are checking, and if selector hasn't any type selector (or even any type selector) it isn't filter.

ids and classes comparison is case sensetive, tags – is not.

Input CSS:

* { color: green; }
ul, ol, li { color: blue; }
UL.foo, span.bar { color: red; }

Usage data:

{
    "tags": ["ul", "LI"]
}

Result CSS:

*{color:green}ul,li{color:blue}ul.foo{color:red}

Scopes

Scopes is designed for CSS scope isolation solutions such as css-modules. Scopes are similar to namespaces and defines lists of class names that exclusively used on some markup. This information allows the optimizer to move rulesets more agressive. Since it assumes selectors from different scopes can't to be matched on the same element. That leads to better ruleset merging.

Suppose we have a file:

.module1-foo { color: red; }
.module1-bar { font-size: 1.5em; background: yellow; }

.module2-baz { color: red; }
.module2-qux { font-size: 1.5em; background: yellow; width: 50px; }

It can be assumed that first two rules never used with second two on the same markup. But trully speaking we cann't know that for sure without markup. The optimizer doesn't know it eather and will perform safe transformations only. The result will be the same as input but with no spaces and some semicolons:

.module1-foo{color:red}.module1-bar{font-size:1.5em;background:#ff0}.module2-baz{color:red}.module2-qux{font-size:1.5em;background:#ff0;width:50px}

But with usage data CSSO can get better output. If follow usage data is provided:

{
    "scopes": [
        ["module1-foo", "module1-bar"],
        ["module2-bar", "module2-baz"]
    ]
}

New result (29 bytes extra saving):

.module1-foo,.module2-baz{color:red}.module1-bar,.module2-qux{font-size:1.5em;background:#ff0}.module2-qux{width:50px}

If class name doesn't specified in scopes it's considered that it belongs to default "scope". scopes doesn't affect classes. If class name present in scopes but missed in classes (both sections specified) it will be filtered.

Note that class name can't be specified in several scopes. Also selector can't has classes from different scopes. In both cases an exception throws.

Currently the optimizer doesn't care about out-of-bounds selectors order changing safety (i.e. selectors that may be matched to elements with no class name of scope, e.g. .scope div or .scope ~ :last-child) since assumes scoped CSS modules doesn't relay on it's order. It may be fix in future if to be an issue.

API

var csso = require('csso');

var compressedCss = csso.minify('.test { color: #ff0000; }');

console.log(compressedCss);
// .test{color:red}


// there are some options you can pass
var compressedWithOptions = csso.minify('.test { color: #ff0000; }', {
    restructure: false,   // don't change css structure, i.e. don't merge declarations, rulesets etc
    debug: true           // show additional debug information:
                          // true or number from 1 to 3 (greater number - more details)
});

You may minify CSS by yourself step by step:

var ast = csso.parse('.test { color: #ff0000; }');
var compressedAst = csso.compress(ast);
var compressedCss = csso.translate(compressedAst, true);

console.log(compressedCss);
// .test{color:red}

Working with source maps:

var css = fs.readFileSync('path/to/my.css', 'utf8');
var result = csso.minify(css, {
  filename: 'path/to/my.css', // will be added to source map as reference to source file
  sourceMap: true             // generate source map
});

console.log(result);
// { css: '...minified...', map: SourceMapGenerator {} }

console.log(result.map.toString());
// '{ .. source map content .. }'

Debugging

> echo '.test { color: green; color: #ff0000 } .foo { color: red }' | csso --debug
## parsing done in 10 ms

Compress block #1
(0.002ms) convertToInternal
(0.000ms) clean
(0.001ms) compress
(0.002ms) prepare
(0.000ms) initialRejoinRuleset
(0.000ms) rejoinAtrule
(0.000ms) disjoin
(0.000ms) buildMaps
(0.000ms) markShorthands
(0.000ms) processShorthand
(0.001ms) restructBlock
(0.000ms) rejoinRuleset
(0.000ms) restructRuleset
## compressing done in 9 ms

.foo,.test{color:red}

More details are provided when --debug flag has a number greater than 1:

> echo '.test { color: green; color: #ff0000 } .foo { color: red }' | csso --debug 2
## parsing done in 8 ms

Compress block #1
(0.000ms) clean
  .test{color:green;color:#ff0000}.foo{color:red}

(0.001ms) compress
  .test{color:green;color:red}.foo{color:red}

...

(0.002ms) restructBlock
  .test{color:red}.foo{color:red}

(0.001ms) rejoinRuleset
  .foo,.test{color:red}

## compressing done in 13 ms

.foo,.test{color:red}

Using --debug option adds stack trace to CSS parse error output. That can help to find out problem in parser.

> echo '.a { color }' | csso --debug

Parse error <stdin>: Colon is expected
    1 |.a { color }
------------------^
    2 |

/usr/local/lib/node_modules/csso/lib/cli.js:243
                throw e;
                ^

Error: Colon is expected
    at parseError (/usr/local/lib/node_modules/csso/lib/parser/index.js:54:17)
    at eat (/usr/local/lib/node_modules/csso/lib/parser/index.js:88:5)
    at getDeclaration (/usr/local/lib/node_modules/csso/lib/parser/index.js:394:5)
    at getBlock (/usr/local/lib/node_modules/csso/lib/parser/index.js:380:27)
    ...

License

MIT

Changelog

1.8.0 (March 24, 2016)

• Usage data support:
  • Filter rulesets by tag names, class names and ids white lists.
  • More aggressive ruleset moving using class name scopes information.
  • New CLI option --usage to pass usage data file.
• Improve initial ruleset merge
  • Change order of ruleset processing, now it's left to right. Previously unmerged rulesets may prevent lookup and other rulesets merge.
  • Difference in pseudo signature just prevents ruleset merging, but don't stop lookup.
  • Simplify block comparison (performance).
• New method csso.minifyBlock() for css block compression (e.g. style attribute content).
• Ruleset merge improvement: at-rules with block (like @media or @supports) now can be skipped during ruleset merge lookup if doesn't contain something prevents it.
• FIX: Add negation (:not()) to pseudo signature to avoid unsafe merge (old browsers doesn't support it).
• FIX: Check nested parts of value when compute compatibility. It fixes unsafe property merging.