postcss-sorting

What is postcss-sorting?

The postcss-sorting npm package is a tool for sorting CSS properties in a specific order. It can be used to enforce a consistent order in CSS files, which can make them more readable and maintainable. It is built as a PostCSS plugin and can be integrated into build processes to automatically sort properties according to a predefined set of rules.

What are postcss-sorting's main functionalities?

Sorting CSS properties

This feature allows developers to automatically sort CSS properties within a stylesheet. The sorting can be customized through options to fit the team's or project's coding standards.

postcss([ require('postcss-sorting')({ /* options */ }) ]).process(css, { from: undefined }).then(result => { console.log(result.css); });

Sorting at-rules

With postcss-sorting, developers can also sort at-rules in a specific order. This can include sorting of media queries, font-face declarations, and other at-rules to improve the structure of the CSS.

postcss([ require('postcss-sorting')({ order: ['custom-properties', 'dollar-variables', 'declarations', 'at-rules', 'rules'] }) ]).process(css, { from: undefined }).then(result => { console.log(result.css); });

Sorting based on custom order

Developers can define a custom order for properties to be sorted. This allows for a highly personalized sorting order that can adhere to specific coding guidelines or preferences.

postcss([ require('postcss-sorting')({ 'properties-order': ['position', 'top', 'right', 'bottom', 'left'] }) ]).process(css, { from: undefined }).then(result => { console.log(result.css); });

Other packages similar to postcss-sorting

stylelint-order

stylelint-order is a plugin for stylelint that checks the order of content within declaration blocks. While it does not automatically sort properties, it can enforce a specific order and report when the order is incorrect.

csscomb

csscomb is a coding style formatter for CSS. Similar to postcss-sorting, it can sort properties according to a specific order. However, csscomb is not a PostCSS plugin and works as a standalone tool or integrated with other code editors.

perfectionist

perfectionist is another PostCSS plugin that beautifies CSS by formatting it according to a consistent standard. It includes sorting capabilities but also focuses on other aspects of beautification, such as indentation and whitespace.

README

PostCSS Sorting

PostCSS plugin to sort rules content with specified order. Heavily inspired by CSSComb.

Features

• Plugin is sorting content for rules and at-rules.
• Sorting nested rules.
• Sorting at-rules, also by at-rule name and parameter.
• Sorting variables.
• Grouping content.
• Currently support CSS, PreCSS and most likely any other syntax added by other PostCSS plugins.

Installation

$ npm install postcss-sorting

Usage

See PostCSS docs for examples for your environment.

Node

require('postcss-sorting').process(YOUR_CSS, { /* options */ });

PostCSS

Add PostCSS to your build tool:

npm install postcss --save-dev

Load PostCSS Sorting as a PostCSS plugin:

postcss([
    require('postcss-sorting')({ /* options */ })
]);

Gulp

Add Gulp PostCSS to your build tool:

npm install gulp-postcss --save-dev

Enable PostCSS Sorting within your Gulpfile:

var postcss = require('gulp-postcss');

gulp.task('css', function () {
    return gulp.src('./css/src/*.css').pipe(
        postcss([
            require('postcss-sorting')({ /* options */ })
        ])
    ).pipe(
        gulp.dest('./css')
    );
});

Grunt

Add Grunt PostCSS to your build tool:

npm install grunt-postcss --save-dev

Enable PostCSS Sorting within your Gruntfile:

grunt.loadNpmTasks('grunt-postcss');

grunt.initConfig({
    postcss: {
        options: {
            processors: [
                require('postcss-sorting')({ /* options */ })
            ]
        },
        dist: {
            src: 'css/*.css'
        }
    }
});

Options

Currently there is only one option.

sort-order

Set sort order. If no order is set, plugin uses default config.

Note: Use one of predefined configs as an example.

Acceptable values:

• {Array} of rules;
• {Array} of arrays of rules for groups separation;
• {String} with the name of predefined config.

Declarations

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

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

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

Grouping

Using array of arrays for sort-order separate content into groups by empty line.

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

@at-rules

Any @at-rule inside other rule can be sorted. There is some keywords:

• @atrule — any at-rule.
• @atrulename — any at-rule with specific name. Ex., @media or @mixin.
• @atrulename parameter — any at-rule with specific name and parameter. Ex., @mixin clearfix.

Example: { "sort-order": ["@atrule", "@mixin", "border", "@some-rule hello", "@mixin clearfix"] }

/* before */
.block {
    @some-rule hello;
    border: none;
    @mixin clearfix;
    @media (min-width: 100px) {
        display: none;
    }
    @mixin island;
}

/* after */
.block {
    @media (min-width: 100px) {
        display: none;
    }
    @mixin island;
    border: none;
    @some-rule hello;
    @mixin clearfix;
}

Nested rules

>child keyword for nested rules.

Example: { "sort-order": [ ["position", "top", "width"], ['>child'] ] }

/* before */
.block {
    position: absolute;

    span {
        display: inline-block;
    }

    width: 50%;

    &__element {
        display: none;
    }

    top: 0;
}

/* after */
.block {
    position: absolute;
    top: 0;
    width: 50%;

    span {
        display: inline-block;
    }
    &__element {
        display: none;
    }
}

Variables

$variable keyword is using to sort variables like $size.

Example: { "sort-order": [ ["$variable"], ["position", "top", "width", "height"] ] }

/* before */
.block {
    position: absolute;
    $width: 10px;
    top: 0;
    $height: 20px;
    height: $height;
    width: $width;
}

/* after */
.block {
    $width: 10px;
    $height: 20px;

    position: absolute;
    top: 0;
    width: $width;
    height: $height;
}

Leftovers

When there are properties that are not mentioned in the sort-order option, they are inserted after all the sorted properties in the new group in the same order they were in the source stylesheet.

You can override this by using a “leftovers” token: ... — just place it either in its own group, or near other properties in any other group and CSSComb would place all the properties that were not sorted where the ... was in sort-order.

So, with this value:

{
    "sort-order": [
        ["$variable"],
        ["position"],
        ["...", "border"],
        ["@mixin"],
        ["font"]
    ]
}

everything would go into five groups: variables, then group with position, then group containing all the leftovers plus the border, then group with all mixins and then the font.

Predefined configs

PostCSS Sorting have predefined configs:

• default
• zen
• csscomb
• yandex

Example: { "sort-order": "zen" }

Thanks

This plugin is heavily inspired by CSSComb. Some code logic, tests and documentation parts are taken from this tool.

Changelog

1.0.1

• Change .npmignore to not deliver unneeded files.