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.

Installation

npm install csscomb

To run csscomb, you can use the following command from the project root:

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

./node_modules/.bin/csscomb --help

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

  Options:

    -h, --help           output usage information
    -V, --version        output the version number
    -c, --config [path]  configuration file path
    -l, --lint           in case some fixes needed returns an error

Configuration

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

Example configuration:

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

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

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 }

$ ./bin/csscomb ./test
✓ test/integral.origin.css
  test/integral.expect.css

2 files processed
1 file fixed
96 ms spent

CLI mode:

$ ./bin/csscomb ./test --verbose
$ ./bin/csscomb ./test -v

always-semicolon

Available value: {Boolean} true

Example: { "always-semicolon": true }

/* before */
a { color: red }

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

block-indent

Note: better to use with rule-indent

Available values:

• {Boolean} true (means 4 spaces)
• {Number} of spaces
• {String} of whitespace characters (/[ \t]+/)

Example: { "block-indent": 2 }

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

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

colon-space

Available values:

• {Boolean} true (means after) or false (no whitespace at all)
• {String}: before, after, both or any combination of whitespaces and/or a colon ( , : , \t:\n\t etc.)
• {Array} with two {String} values: for setting left and right whitespace around a colon

Example: { "colon-space": true }

/* before */
a { color:red }

/* after */
a { color: red }

Example: { "colon-space": ":\n\t\t" }

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

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

Example: { "colon-space": "" }

/* before */
a { color: red }

/* after */
a { color:red }

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

/* 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

Available values:

• {Boolean}: true sets one space, false removes the spaces.
• {String}: any combination of whitespaces.
• {Array} with two {String} values: for setting left and right whitespace.

Example: { "combinator-space": true }

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

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

Example: { "combinator-space": "" }

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

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

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

/* 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 }

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

Available values:

• {Boolean} true (means 4 spaces)
• {Number} of spaces
• {String} of whitespace characters (/[ \t]+/)

Example: { "rule-indent": 2 }

/* 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;
}

stick-brace

Available values:

• {Boolean} true (means 1 space)
• {Number} of spaces
• {String} of whitespace characters (/[ \t\n]+/)

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

/* 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

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/css/csso
• https://github.com/nzakas/parser-lib