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 sorting properties in a specific order. It was inspired by @miripiruni's PHP-based tool of the same name. This is the new JavaScript version, based on the powerful CSS parser Gonzales PE.

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

npm install csscomb -g

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

npm install csscomb

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

npm install csscomb --save

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

npm install csscomb --save-dev

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

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');

You must configure csscomb before use. The config must be valid JSON.
See configuration section for more information.

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

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

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

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

comb.processDirectory('public/css');

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');

Comb a stylesheet.
If syntax is not css, you should pass a syntax parameter, too.
filename is optional. It is used to print 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');

csscomb is configured using the file .csscomb.json, 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
}

Note: you can also use a predefined config file

cp ./node_modules/csscomb/config/csscomb.json .csscomb.json

Instead of configuring all the options one by one, you can use a CSS-template file: CSSComb.js will detect the coding style and use it as a config. All existing properties except sort-order can 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 will only create rules based on the examples given, so if your template doesn't provide examples of usage for some of the options, or if you want to override an example, you can write them in the .csscomb.json after the "template":

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

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

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

.foo
{
    width: #fff;
}

running

csscomb -d template.css > .csscomb.json

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": "    "
}

Available values: {String[]}

Array of Ant path patterns to exclude.

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

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

Note: see the description of the configuring with templates.

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

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

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

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

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

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

Acceptable values are of the form {Array} with 2 elements of the 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 }

Available values: {String} lower or upper

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

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

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

Available values: {Boolean} true or false

Example: { "color-shorthand": true }

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

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

Acceptable value is {Array} with 2 elements of the 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 }

Acceptable values: {String} lower or upper

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

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

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

Acceptable 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 }

Acceptable values: {Boolean} true or false

Example: { "leading-zero": false }

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

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

Acceptable values: {String} single or double

Example: { "quotes": "single" }

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

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

Acceptable values: {Boolean} true

Example: { "remove-empty-rulesets": true } - remove rulesets that have nothing but spaces.

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

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 }

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

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 }

Acceptable value: {Boolean} true

Example: { "strip-spaces": true }

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

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

Acceptable value: {Boolean} true

Example: { "unitless-zero": true }

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

/* after */
img { border: 0 }

Acceptable 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%);
}

Run npm test for tests.

To check test coverage, you need jscoverage tool. Once it is installed (see instructions here), run:

npm run-script test-cov
open ./test/test-coverage.html

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

@mishanga, @tonyganch

Thanks for assistance and contributions:

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

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

• 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