CSS Declaration Sorter

A Node.js module and PostCSS plugin to sort CSS, SCSS or Less declarations based on their property names. Ensuring styling is organized, more consistent and in order... The goal of this package is to sort the source code of a project in the build process or to decrease the distributed CSS gzipped size. Check out the Atom package for individual usage.

Niceness

• Up-to-date CSS properties fetched from the MDN Web Platform.
• Choose your wanted order or provide your own.
• Nested rules sorting support.
• SCSS and Less support when combined with either postcss-scss or postcss-less.
• Thought-out sorting orders out of the box, approved by their authors.

Alphabetical example

Input:

body {
    display: block;
    animation: none;
    color: #C55;
    border: 0;
}

Output:

body {
    animation: none;
    border: 0;
    color: #C55;
    display: block;
}

Built-in sorting orders

• Alphabetical
  alphabetical
  Default, order in a simple alphabetical manner from a - z.

• SMACSS
  smacss
  Order from most important, flow affecting properties, to least important properties.

  1. Box
  2. Border
  3. Background
  4. Text
  5. Other

• Concentric CSS
  concentric-css
  Order properties applying outside the box model, moving inward to intrinsic changes.

  1. Positioning
  2. Visibility
  3. Box model
  4. Dimensions
  5. Text

Usage

npm install css-declaration-sorter --save-dev

CLI

This module does not include its own CLI but works with the official PostCSS CLI. To use the examples below, the postcss-cli package is a required dependency.

Piping out result from file:
postcss input.css --use css-declaration-sorter | cat

Sorting multiple files by overwriting:
postcss *.css --use css-declaration-sorter --replace --no-map

Vanilla JS

const postcss = require('postcss');
const cssDeclarationSorter = require('css-declaration-sorter');

postcss([cssDeclarationSorter({order: 'smacss'})])
  .process('a { color: hyperblue; display: block; }')
  .then(result =>
    result.css === 'a { display: block; color: hyperblue; }'
  );

Gulp

const gulp = require('gulp');
const gulpPostcss = require('gulp-postcss');
const cssDeclarationSorter = require('css-declaration-sorter');

gulp.task('css', function () {
  return gulp.src('some.css')
    .pipe(gulpPostcss([cssDeclarationSorter({order: 'smacss'})]))
    .pipe(gulp.dest('./'));
});

See PostCSS documentation for more examples and other environments.

API

cssDeclarationSorter({ order, keepOverrides })

order

Type: string or function
Default: alphabetical
Options: alphabetical, smacss, concentric-css

Provide the name of one of the built-in sort orders or a comparison function that is passed to (Array.sort). This function receives two declaration names and is expected to return -1, 0 or 1 depending on the wanted order.

keepOverrides

Type: Boolean Default: false

To prevent breaking legacy CSS where shorthand declarations override longhand declarations this option can enabled. For example animation-name: some; animation: greeting; will be kept in this order when keepOverrides is true.