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 minimizer unlike others. In addition to usual minification techniques it can perform structural optimization of CSS files, resulting in smaller file size compared to other minifiers.

Install

npm install -g csso

Usage

Runners

• Gulp: gulp-csso
• Grunt: grunt-csso
• Broccoli: broccoli-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. Possible values: none, auto (default) or <filename>
  -m, --map <destination>   Generate source map. Possible values: 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
  -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 }' | node bin/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 – generate map add it into result content (via /*# sourceMappingURL=application/json;base64,...base64 encoded map... */)
• file – generate map and write it 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 --map file --output my.min.css
> csso my.css -o my.min.css -m maps/my.min.map

Input can has a source map. Use --input-map option to specify input source if needed. Possible values for option:

• auto (auto) - attempt to fetch input source map by follow steps:
  • try to fetch inline map from source
  • try to fetch map filename from source and read its content
  • (when --input is specified) check for file with same name as input 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 as filename for input source map

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

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 do it 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 file
  sourceMap: true             // generate source map
});

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

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

// apply input source map
var SourceMapConsumer = require('source-map').SourceMapConsumer;
var inputSourceMap = fs.readFileSync('path/to/my.map.css', 'utf8');

result.map.applySourceMap(
  new SourceMapConsumer(inputSourceMap),
  'path/to/my.css'  // should be the same as passed to csso.minify()
);

// if no input source map you may add source content
result.map.setContent('path/to/my.css', setSourceContent);

Debugging

> echo '.test { color: green; color: #ff0000 } .foo { color: red }' | node bin/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 }' | node bin/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.6.2 (February 29, 2016)

• tweak some parse error messages and their positions
• fix :not() parsing and selector groups in :not() is supported now (#215)
• needPosition parser option is deprecated, positions option should be used instead (needPosition is used still if positions option omitted)
• expose internal AST API as csso.internal.*
• minify() adds sourcesContent by default when source map is generated
• bring back support for node.js 0.10 until major release (#275)