CSScomb 3.0: beautiful code with one team

This week a new version of CSScomb is released - a tool that makes CSS code beautiful. About how the "comb" is used in Yandex, recently wrote Beyondtheclouds . I’ll tell you what new appeared in the third version and what to do if the basic functionality is not enough. For example, how to write your own plugin or even a post processor.

First about the new.

Sass Support

Indentation buffs can now tidy up sass files.

// До:
.panda,.foo>span
    border-color:$blue
    +include buttoncolor:  darken($blue, 9%)
    $blue : #3bbfce
    padding:$margin / 2
    $margin: 16px
    margin: $margin / 2// После:
.panda, .foo > span
    $blue: #3bbfce
    $margin: 16px
    +button
    padding: $margin / 2
    margin: $margin / 2
    border-color: $blue
    color: darken($blue, 9%)

Stylus never appeared and is not expected in the near future. Difficulties arose not so much with writing code as with its support: there was no person who would be ready to follow the latest in the language and update the parser. Details can be read in the corresponding task .

"Leftovers" in sorting

A new keyword has appeared for the sort order: "..."which means "all other properties not listed." It is convenient to use it in two cases:

for alphabetical sorting (see below)
for selective sorting

An example of selective sorting:

// До:
.panda {
    color: $color;
    @include animal;
    top: 0;
    $color: white;
}
/**
 * После применения этого конфига:
 * {
 *   sort-order: [["$variable"], ["..."], ["$include"]]
 * }
 */
.panda {
    $color: white;
    color: $color;
    top: 0;
    @include animal;
}

Alphabetical Sort

You can argue about which order of properties is better, endlessly. We decided to make your work easier and added a property sort-order-fallback. This option sorts alphabetically the properties indicated by the keyword in the list "...".

// До:
.panda {
    background: salmon;
    display: flex;
    align-items: center;
    color: white;
}
/**
 * После применения этого конфига:
 * {
 *   "sort-order": ["..."],
 *   "sort-order-fallback": "abc"
 * }
 */
.panda {
    align-items: center;
    background: salmon;
    color: white;
    display: flex;
}

This property can also be combined with selective sorting.

.panda {
    background: salmon;
    @include animal;
    display: flex;
    align-items: center;
    color: white;
}
/**
 * После применения этого конфига:
 * {
 *   "sort-order": [[$include"], ["display"], ["..."]],
 *   "sort-order-fallback": "abc"
 * }
 */
.panda {
    @include animal;
    display: flex;
    align-items: center;
    background: salmon;
    color: white;
}

New settings

The third version improves the work with spaces. We deleted some settings ( rule-indent, stick-brace). Some pitched and renamed. So, it combinator-spaceturned into space-before-combinatorand space-after-combinator, and colon-space- into space-before-colonand space-after-colon.
We also added a number of new options:

tab-size
space-before-selector-delimiter
space-after-selector-delimiter
space-before-opening-brace
space-after-opening-brace
space-before-closing-brace
space-after-declaration

A complete list and examples of use can be found on the github .

How to upgrade

CSScomb can be obtained in several ways:

In addition, there are plugins for Gulp , for Brunch and for Brackets , but they do not yet support version 3.0.
If you are using CSScomb 2.0 and want to upgrade to the third version, updating the config is very important. With the old, unfortunately, will not take off.
So that you do not have to spend time redoing the file with your hands, we made a service for generating configs . All you need to do is click on the code options that you like. The output will be a settings file ready for operation.

How to extend functionality

CSScomb is a great tool, but sometimes you want to add something. Therefore, we tried to make the code as modular and easily extensible. You can supplement the "comb" with the desired function without bothering with the fork. There are three ways to do this:

connect a third-party plugin
write your plugin
make your postprocessor based on CSScomb

3rd party plugins

The easiest way to use someone else's plugin. For example, here is an option that removes an empty line between groups of declarations if there are too few declarations in the group. Connecting the plugin is quite simple, there is a method for this use():

var CSScomb = require('csscomb');
var groupSize = require('csscomb-group-size');
// Число 4 означает, что если в группе меньше 4 деклараций, между этой// группой и предыдущей уберётся пустая строка-разделитель:var config = { 'group-size': 4 };
// Создаём новый экземпляр «расчёски»:var csscomb = new CSScomb().use(groupSize).configure(config);
// Творим чудеса:
csscomb.processPath('path/to/css');

Since the ability to write plugins has just appeared, there is not much variety yet. Therefore, if you know exactly what you are missing, you can write your own option.

Write your plugin

A plugin is a common module with methods for processing AST. The documentation is available on the github . Gonzales PE is used as a parser ; the documentation on the tree structure is on the github . Here is the simplest example of a plugin that takes CSS code and replaces all comments in it with /* (╯°□°）╯︵ ┻━┻ */:

module.exports = {
    name: 'flip-comments',
    syntax: ['css'],
    accepts: {
        boolean: [true]
    },
    process: function(nodeType, node) {
        if (nodeType !== 'commentML') return;
        node[0] = ' (╯°□°）╯︵ ┻━┻ ';
    }
};

The same code, only with comments.

Make your options and share links with the community. If you have questions, feel free to write in the comments or immediately start the task.

Write your post processor

If the plugin is not enough and you need something much more, why not write your own post processor? We have taken out CSScomb core in a separate module so that anyone can apply it for their project. Therefore, if you like the "comb" working principle, the system of plug-ins and settings files, pay attention to CSScomb Core . Inside this module there is everything you need:

Parser with preprocessor support
API for working with configs
API for creating and connecting plugins
API for processing files / lines / directories

A quick template, Flip Comb , will help you figure it out . This is a small post processor, nothing is worth it. The code can be forked and changed to fit your needs.

Future plans

The main area of further improvements is the linter and CLI.
We tried to write the options ourselves, without waiting for their appearance in the kernel. Therefore, you should not wait for new settings in the near future. But if you wrote a plugin and think that it will be useful to others, too, it's very cool, send PR.
If you are interested in participating in the project, pay attention to the tasks with the help help tag . Stylus, for example, is still waiting for its hero.

All links in one place

CSScomb: https://github.com/csscomb/csscomb.js
CSScomb Core: https://github.com/csscomb/core
Template postprocessor based Core CSScomb: https://github.com/csscomb/core-template
Service to generate the config: http://csscomb.com/config

PS Hosting for csscomb.com is provided to us by Nodejitsu for free as part of the open source support program . There are not many resources, so if the site suddenly becomes unavailable, please be understanding.

Tags:

CSScomb