CSSComb

CSSComb is a coding style formatter for CSS. You can easily write your own configuration to make your style sheets beautiful and consistent.

The main feature is the sorting properties in specific order. It was inspired by the same-named @miripiruni's PHP-based tool. This is the new JavaScript version, based on powerful CSS parser Gonzales PE.

Installation

Global installation (use as a command-line tool):

npm install csscomb -g

Local installation (use as a command-line tool within current directory):

npm install csscomb

To install as a project dependency (package will appear in your dependencies):

npm install csscomb --save

To install as a dev dependency (package will appear in your devDependencies):

npm install csscomb --save-dev

CLI usage

To run csscomb:

csscomb path[ path[...]]

If you installed the package locally, in the project's directory run:

./node_modules/.bin/csscomb path[ path[...]]

If you run csscomb -h, it will show some helpful information:

csscomb -h

  Usage: csscomb [options] <file ...>

  Options:

    -h, --help           output usage information
    -V, --version        output the version number
    -v, --verbose        verbose mode
    -c, --config [path]  configuration file path
    -d, --detect         detect mode (would return detected options)
    -l, --lint           in case some fixes needed returns an error

Node.js module usage

Besides being a great CLI, csscomb can be used in Node.js projects (inside a plugin or as a dev tool):

// Require:
var Comb = require('csscomb');

// Configure:
var comb = new Comb();
comb.configure(config);

// Use:
comb.processPath('style.css');

configure(config)

You must configure csscomb before using and config must be a valid JSON.
See configuration section for more information.

processPath(path)

Comb a file or a directory.
Warning: This method rewrites the file.

// One file:
comb.processPath('main.scss');

// Whole directory:
comb.processPath('assets/styles');

processDirectory(path)

Comb all supported files in a directory.
Warning: This method rewrites the files.

comb.processDirectory('public/css');

processFile(path)

Comb one file.
If file's syntax is not supported, the file will be ignored.
Warning: This method rewrites the file.

comb.processFile('print.less');

processString(text, syntax, filename)

Comb a stylesheet.
If style's syntax is different from css, you should pass syntax parameter, too.
filename is optional, it's used to print possible errors.

// Comb a css string:
var css = 'a {top: 0; left: 0}';
var combedCSS = comb.processString(css);

// Comb a less string:
var less = '@color: tomato; a {color: @color}';
var combedLESS = comb.processString(less, 'less');

Configuration

Through .csscomb.json

csscomb is configured using .csscomb.json file, located in the project root.

Example configuration:

{
    "exclude": ["node_modules/**"],
    "verbose": true,

    "always-semicolon": true,
    "block-indent": "    ",
    "colon-space": ["", " "],
    "color-case": "lower",
    "color-shorthand": true,
    "element-case": "lower",
    "eof-newline": true,
    "leading-zero": false,
    "quotes": "single",
    "remove-empty-rulesets": true,
    "rule-indent": "    ",
    "stick-brace": "\n",
    "strip-spaces": true,
    "unitless-zero": true,
    "vendor-prefix-align": true
}

Through .css-template

Instead of configuring all the options one by one, you can use a CSS-template file instead: CSSComb.js would detect the codestyle used in this file and would use it as a config. All the existent properties except for the sort-order could be configured this way.

To provide a template just add "template" with the path to the template in the .csscomb.json:

{
    "template": "example.css"
}

CSSComb.js would detect only those things that could be detected, so if your template don't provide examples of usage for some of the options, or if you would want to override something from it, you can write them in the .csscomb.json along the "template":

{
    "template": "example.css",
    "leading-zero": false,
    "vendor-prefix-align": true
}

This config would detect all the options from the example.css, then it would use "leading-zero": false instead of what it detected, and then it would use "vendor-prefix-align": true even if there were no prefixed properties or values inside the example.css.

Creating .csscomb.json from the .css file

If you want to configure everything manually, but based on the codestyle from existing .css-file, you can at first detect all the options using --detect CLI option, and then add/edit any options you like. So if you have such example.css:

.foo
{
    width: #fff;
}

then by running

csscomb -d template.css > .csscomb.json

you would generate this .csscomb.json:

{
    "remove-empty-rulesets": true,
    "always-semicolon": true,
    "color-case": "lower",
    "color-shorthand": true,
    "strip-spaces": true,
    "eof-newline": true,
    "stick-brace": "\n",
    "colon-space": [
        "",
        " "
    ],
    "rule-indent": "    "
}

Options

exclude

Available values: {String[]}

Array of Ant path patterns to exclude.

Example: { "exclude": ["node_modules/**"] } - exclude all files and directories under node_modules dir.

verbose

Available value: {Boolean} true

Config mode: { "verbose": true }

csscomb ./test

✓ test/integral.origin.css
  test/integral.expect.css

2 files processed
1 file fixed
96 ms spent

CLI mode:

csscomb --verbose ./test
csscomb -v ./test

template

Note: see the description of the configuring through template.

Available value: {String} path to the .css file.

Example: { "template": "example.css" }

CLI mode — just provide path to .css file instead of .csscomb.json:

csscomb --config example.css ./test
csscomb -c example.css ./test

always-semicolon

Whether to add a semicolon after the last value/mixin.

Available value: {Boolean} true

Example: { "always-semicolon": true }

/* before */
a { color: red }

/* after */
a { color: red; }

Example: { "always-semicolon": true } (scss file):

// before
div {
    color: tomato;
    @include nani
    }

// after
div {
    color: tomato;
    @include nani;
    }

Note that in *.scss and *.less files semicolons are not added after } even if it's part of a value:

// before
div {
    color: tomato;
    font: {
        family: fantasy;
        size: 16px
        }
    }

// after
div {
    color: tomato;
    font: {
        family: fantasy;
        size: 16px;
        }
    }

block-indent

Note: better to use with rule-indent

Acceptable values:

• {Number} of spaces;
• {String} of whitespaces or tabs. If there is any other character in the string, the value will not be set.

Example: { "block-indent": 2 }

/* before */
  a { color: red }
  @media all { a { color: green } }

/* after */
a { color: red
}
@media all {
  a { color: green
  }
}

Example: { "block-indent": " " }

/* before */
  a { color: red }
  @media all { a { color: green } }

/* after */
a { color: red
}
@media all {
  a { color: green
  }
}

colon-space

Acceptable value is {Array} with 2 elements of following types:

• {Number} of spaces;
• {String} of whitespaces or tabs. If there is any other character in the string, the value will not be set.

The first element of the array sets spaces before colon, and the second one sets spaces after colon.

Example: { "colon-space": ["\t", "\t"] }

/* before */
a { color: red }

/* after */
a { color	:	red }

Example: { "colon-space": [0, 1] }

/* before */
a { color:red }

/* after */
a { color: red }

color-case

Available values: {String} lower or upper

Example: { "color-case": "lower" }

/* before */
a { color: #FFF }

/* after */
a { color: #fff }

color-shorthand

Available values: {Boolean} true or false

Example: { "color-shorthand": true }

/* before */
b { color: #ffcc00 }

/* after */
b { color: #fc0 }

combinator-space

Acceptable value is {Array} with 2 elements of following types:

• {Number} of spaces;
• {String} of whitespaces, tabs or new lines. If there is any other character in the string, the value will not be set.

The first element of the array sets spaces before combinator, and the second one sets spaces after combinator.

Example: { "combinator-space": [" ", "\n"] }

/* before */
a>b { color: red }

/* after */
a >
b { color: red }

Example: { "combinator-space": [1, 1] }

/* before */
a>b { color: red }

/* after */
a > b { color: red }

element-case

Available values: {String} lower or upper

Example: { "element-case": "upper" }

/* before */
li > a { color: red }

/* after */
LI > A { color: red }

eof-newline

Available values: {Boolean} true or false

Example: { "eof-newline": true }

a { color: red } → a { color: red }\n

Example: { "eof-newline": false }

a { color: red }\n → a { color: red }

leading-zero

Available values: {Boolean} true or false

Example: { "leading-zero": false }

/* before */
p { padding: 0.5em }

/* after */
p { padding: .5em }

quotes

Available values: {String} single or double

Example: { "quotes": "single" }

/* before */
p[href^="https://"]:before { content: "secure" }

/* after */
p[href^='https://']:before { content: 'secure' }

remove-empty-rulesets

Available values: {Boolean} true

Example: { "remove-empty-rulesets": true } - remove rulesets that have no declarations or comments.

a { color: red; } p { /* hey */ } b { } → a { color: red; } p { /* hey */ }

rule-indent

Note: better to use with block-indent

Acceptable values:

• {Number} of spaces;
• {String} of whitespaces or tabs. If there is any other character in the string, the value will not be set.

Example: { "rule-indent": 2 }

/* before */
a { color:red; margin:0 }

/* after */
a {
  color:red;
  margin:0 }

Example: { "rule-indent": " " }

/* before */
a { color:red; margin:0 }

/* after */
a {
  color:red;
  margin:0 }

sort-order

Note: you can use an example of .csscomb.json to set your own sort order

Available values:

• {Array} of rules
• {Array} of arrays of rules for groups separation

Example: { "sort-order": [ "margin", "padding" ] }

/* before */
p {
    padding: 0;
    margin: 0;
}

/* after */
p {
    margin: 0;
    padding: 0;
}

Example: { "sort-order": [ [ "margin", "padding" ], [ "border", "background" ] ] }

/* before */
p {
    background: none;
    border: 0;
    margin: 0;
    padding: 0;
}

/* after */
p {
    margin: 0;
    padding: 0;

    border: 0;
    background: none;
}

If you sort properties in *.scss or *.less files, you can use one of 3 keywords in your config:

• $variable for variable declarations (e.g. $var in Sass or @var in LESS);
• $include for included mixins (e.g. @include ... and @extend ... in Sass or .mixin() in LESS);
• $import for @import rules.

Example: { "sort-order": [ [ "$variable" ], [ "$include" ], [ "top", "padding" ] ] }

/* before */
p {
    padding: 0;
    @include mixin($color);
    $color: tomato;
    top: 0;
}

/* after */
p {
    $color: tomato;

    @include mixin($color);

    top: 0;
    padding: 0;
}

stick-brace

Acceptable values:

• {Number} of spaces;
• {String} of whitespaces, tabs or newlines. If there is any other character in the string, the value will not be set.

Example: { "stick-brace": "\n" }

/* before */
a { color:red }

/* after */
a
{ color:red }

Example: { "stick-brace": 1 }

/* before */
a{ color:red }

/* after */
a { color:red }

strip-spaces

Available value: {Boolean} true

Example: { "strip-spaces": true }

a { color: red } \n \n \n → a { color: red }\n

a { color: red }\t → a { color: red }

unitless-zero

Available value: {Boolean} true

Example: { "unitless-zero": true }

/* before */
img { border: 0px }

/* after */
img { border: 0 }

vendor-prefix-align

Available value: {Boolean} true

Example: { "vendor-prefix-align": true }

/* before */
a
{
    -webkit-border-radius: 3px;
    -moz-border-radius: 3px;
    border-radius: 3px;
    background: -webkit-linear-gradient(top, #fff 0, #eee 100%);
    background: -moz-linear-gradient(top, #fff 0, #eee 100%);
    background: linear-gradient(to bottom, #fff 0, #eee 100%);
}

/* after */
a
{
    -webkit-border-radius: 3px;
       -moz-border-radius: 3px;
            border-radius: 3px;
    background: -webkit-linear-gradient(top, #fff 0, #eee 100%);
    background:    -moz-linear-gradient(top, #fff 0, #eee 100%);
    background:         linear-gradient(to bottom, #fff 0, #eee 100%);
}

Tests

Run npm test for tests.

Contributing

Anyone and everyone is welcome to contribute. Please take a moment to review the guidelines for contributing.

Authors

@mishanga, @tonyganch

Thanks for assistance and contributions:

@miripiruni, @puzankov, @L0stSoul, @ignovak, @kizu, @anton-rudeshko, @mishaberezin

License

This software is released under the terms of the MIT license.

Other projects

• https://github.com/senchalabs/cssbeautify
• https://github.com/css/gonzales
• https://github.com/tonyganch/gonzales-pe
• https://github.com/css/csso
• https://github.com/nzakas/parser-lib