Spaces:
Configuration error
CSSO (CSS Optimizer) is a CSS minifier. It performs three sort of transformations: cleaning (removing redundants), compression (replacement for the shorter forms) and restructuring (merge of declarations, rules and so on). As a result an output CSS becomes much smaller in size.
Install
npm install csso
Usage
import { minify } from 'csso';
// CommonJS is also supported
// const { minify } = require('csso');
const minifiedCss = minify('.test { color: #ff0000; }').css;
console.log(minifiedCss);
// .test{color:red}
Bundles are also available for use in a browser:
dist/csso.js
β minified IIFE withcsso
as global
<script src="node_modules/csso/dist/csso.js"></script>
<script>
csso.minify('.example { color: green }');
</script>
dist/csso.esm.js
β minified ES module
<script type="module">
import { minify } from 'node_modules/csso/dist/csso.esm.js'
minify('.example { color: green }');
</script>
One of CDN services like unpkg
or jsDelivr
can be used. By default (for short path) a ESM version is exposing. For IIFE version a full path to a bundle should be specified:
<!-- ESM -->
<script type="module">
import * as csstree from 'https://cdn.jsdelivr.net/npm/csso';
import * as csstree from 'https://unpkg.com/csso';
</script>
<!-- IIFE with an export to global -->
<script src="https://cdn.jsdelivr.net/npm/csso/dist/csso.js"></script>
<script src="https://unpkg.com/csso/dist/csso.js"></script>
CSSO is based on CSSTree to parse CSS into AST, AST traversal and to generate AST back to CSS. All CSSTree
API is available behind syntax
field extended with compress()
method. You may minify CSS step by step:
import { syntax } from 'csso';
const ast = syntax.parse('.test { color: #ff0000; }');
const compressedAst = syntax.compress(ast).ast;
const minifiedCss = syntax.generate(compressedAst);
console.log(minifiedCss);
// .test{color:red}
Also syntax can be imported using csso/syntax
entry point:
import { parse, compress, generate } from 'csso/syntax';
const ast = parse('.test { color: #ff0000; }');
const compressedAst = compress(ast).ast;
const minifiedCss = generate(compressedAst);
console.log(minifiedCss);
// .test{color:red}
Warning: CSSO doesn't guarantee API behind a
syntax
field as well as AST format. Both might be changed with changes in CSSTree. If you rely heavily onsyntax
API, a better option might be to use CSSTree directly.
Related projects
- Web interface
- csso-cli β command line interface
- gulp-csso β
Gulp
plugin - grunt-csso β
Grunt
plugin - broccoli-csso β
Broccoli
plugin - postcss-csso β
PostCSS
plugin - csso-loader β
webpack
loader - csso-webpack-plugin β
webpack
plugin - CSSO Visual Studio Code plugin
- vscode-csso - Visual Studio Code plugin
- atom-csso - Atom plugin
- Sublime-csso - Sublime plugin
API
- minify(source[, options])
- minifyBlock(source[, options])
- syntax.compress(ast[, options])
- Source maps
- Usage data
minify(source[, options])
Minify source
CSS passed as String
.
const result = 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)
});
console.log(result.css);
// > .test{color:red}
Returns an object with properties:
- css
String
β resulting CSS - map
Object
β instance ofSourceMapGenerator
ornull
Options:
sourceMap
Type:
Boolean
Default:false
Generate a source map when
true
.filename
Type:
String
Default:'<unknown>'
Filename of input CSS, uses for source map generation.
debug
Type:
Boolean
Default:false
Output debug information to
stderr
.beforeCompress
Type:
function(ast, options)
orArray<function(ast, options)>
ornull
Default:null
Called right after parse is run.
afterCompress
Type:
function(compressResult, options)
orArray<function(compressResult, options)>
ornull
Default:null
Called right after
syntax.compress()
is run.Other options are the same as for
syntax.compress()
function.
minifyBlock(source[, options])
The same as minify()
but for list of declarations. Usually it's a style
attribute value.
const result = csso.minifyBlock('color: rgba(255, 0, 0, 1); color: #ff0000');
console.log(result.css);
// > color:red
syntax.compress(ast[, options])
Does the main task β compress an AST. This is CSSO's extension in CSSTree syntax API.
NOTE:
syntax.compress()
performs AST compression by transforming input AST by default (since AST cloning is expensive and needed in rare cases). Useclone
option with truthy value in case you want to keep input AST untouched.
Returns an object with properties:
- ast
Object
β resulting AST
Options:
restructure
Type:
Boolean
Default:true
Disable or enable a structure optimisations.
forceMediaMerge
Type:
Boolean
Default:false
Enables merging of
@media
rules with the same media query by splitted by other rules. The optimisation is unsafe in general, but should work fine in most cases. Use it on your own risk.clone
Type:
Boolean
Default:false
Transform a copy of input AST if
true
. Useful in case of AST reuse.comments
Type:
String
orBoolean
Default:true
Specify what comments to leave:
'exclamation'
ortrue
β leave all exclamation comments (i.e./*! .. */
)'first-exclamation'
β remove every comment except first onefalse
β remove all comments
usage
Type:
Object
ornull
Default:null
Usage data for advanced optimisations (see Usage data for details)
logger
Type:
Function
ornull
Default:null
Function to track every step of transformation.
Source maps
To get a source map set true
for sourceMap
option. Additianaly filename
option can be passed to specify source file. When sourceMap
option is true
, map
field of result object will contain a SourceMapGenerator
instance. This object can be mixed with another source map or translated to string.
const csso = require('csso');
const css = fs.readFileSync('path/to/my.css', 'utf8');
const 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 .. }'
Example of generating source map with respect of source map from input CSS:
import { SourceMapConsumer } from 'source-map';
import * as csso from 'csso';
const inputFile = 'path/to/my.css';
const input = fs.readFileSync(inputFile, 'utf8');
const inputMap = input.match(/\/\*# sourceMappingURL=(\S+)\s*\*\/\s*$/);
const output = csso.minify(input, {
filename: inputFile,
sourceMap: true
});
// apply input source map to output
if (inputMap) {
output.map.applySourceMap(
new SourceMapConsumer(inputMap[1]),
inputFile
)
}
// result CSS with source map
console.log(
output.css +
'/*# sourceMappingURL=data:application/json;base64,' +
Buffer.from(output.map.toString()).toString('base64') +
' */'
);
Usage data
CSSO
can use data about how CSS
is used in a markup for better compression. File with this data (JSON
) can be set using usage
option. Usage data may contain following sections:
blacklist
β a set of black lists (see Black list filtering)tags
β white list of tagsids
β white list of idsclasses
β white list of classesscopes
β groups of classes which never used with classes from other groups on the same element
All sections are optional. Value of tags
, ids
and classes
should be an array of a string, value of scopes
should be an array of arrays of strings. Other values are ignoring.
White list filtering
tags
, ids
and classes
are using on clean stage to filter selectors that contain something not in the lists. 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 all type selectors in selector present in list or selector has no any type selector it isn't filter.
ids
andclasses
are case sensitive,tags
β is not.
Input CSS:
* { color: green; }
ul, ol, li { color: blue; }
UL.foo, span.bar { color: red; }
Usage data:
{
"tags": ["ul", "LI"]
}
Resulting CSS:
*{color:green}ul,li{color:blue}ul.foo{color:red}
Filtering performs for nested selectors too. :not()
pseudos content is ignoring since the result of matching is unpredictable. Example for the same usage data as above:
:nth-child(2n of ul, ol) { color: red }
:nth-child(3n + 1 of img) { color: yellow }
:not(div, ol, ul) { color: green }
:has(:matches(ul, ol), ul, ol) { color: blue }
Turns into:
:nth-child(2n of ul){color:red}:not(div,ol,ul){color:green}:has(:matches(ul),ul){color:blue}
Black list filtering
Black list filtering performs the same as white list filtering, but filters things that mentioned in the lists. blacklist
can contain the lists tags
, ids
and classes
.
Black list has a higher priority, so when something mentioned in the white list and in the black list then white list occurrence is ignoring. The :not()
pseudos content ignoring as well.
* { color: green; }
ul, ol, li { color: blue; }
UL.foo, li.bar { color: red; }
Usage data:
{
"blacklist": {
"tags": ["ul"]
},
"tags": ["ul", "LI"]
}
Resulting CSS:
*{color:green}li{color:blue}li.bar{color:red}
Scopes
Scopes is designed for CSS scope isolation solutions such as css-modules. Scopes are similar to namespaces and define lists of class names that exclusively used on some markup. This information allows the optimizer to move rules more agressive. Since it assumes selectors from different scopes don't match for the same element. This can improve rule 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 are never used with the second two on the same markup. But we can't say that for sure without a markup review. The optimizer doesn't know it either 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}
With usage data CSSO
can produce better output. If follow usage data is provided:
{
"scopes": [
["module1-foo", "module1-bar"],
["module2-baz", "module2-qux"]
]
}
The result will be (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 isn't mentioned in the scopes
it belongs to default scope. scopes
data doesn't affect classes
whitelist. If class name mentioned in scopes
but missed in classes
(both sections are specified) it will be filtered.
Note that class name can't be set for several scopes. Also a selector can't have class names from different scopes. In both cases an exception will thrown.
Currently the optimizer doesn't care about changing order safety for out-of-bounds selectors (i.e. selectors that match to elements without class name, e.g. .scope div
or .scope ~ :last-child
). It assumes that scoped CSS modules doesn't relay on it's order. It may be fix in future if to be an issue.