css-declaration-sorter

Introducing CSS Declaration Sorter

CSS Declaration Sorter is a powerful tool for developers working with CSS, SCSS, or Less. Crafted as a Node.js module and a PostCSS plugin, this utility aids in restructuring CSS declarations to follow a consistent, organized order based on property names. The primary objective of using CSS Declaration Sorter is to enhance code organization during the build process and to minimize the gzipped size of distributed CSS files.

Developers can also explore the Prettier plugin for broader usage with different file formats.

Key Features

• Up-to-Date Properties: The tool is continually updated with CSS properties based on the MDN Compatibility Data project.
• Custom Ordering: Users have the flexibility to choose predefined orders or define their own custom order.
• Nested Rules Support: It can sort nested rules seamlessly.
• SCSS and Less Compatible: When paired with postcss-scss or postcss-less, it supports SCSS and Less files.
• Ready-to-Use Sorting Orders: Various sorting orders are available, thoughtfully curated and approved by experienced authors.

Example of Alphabetical Order

Before:

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

After:

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

Built-in Sorting Orders

1. Alphabetical: Sorts from a to z, and is the default order.
2. SMACSS: Following the SMACSS format, it prioritizes flow-affecting properties.
   • Box
   • Border
   • Background
   • Text
   • Other
3. Concentric CSS: Adopts the Concentric CSS approach, moving from external properties inward.
   • Positioning
   • Visibility
   • Box model
   • Dimensions
   • Text

How to Use

Installation

To start using CSS Declaration Sorter with PostCSS:

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

Command Line Interface (CLI)

Though it doesn't have its own CLI, it integrates seamlessly with the PostCSS CLI. Here are some usage examples:

• Process a single file:

  postcss input.css --use css-declaration-sorter | cat
  

• Sort multiple files:

  postcss *.css --use css-declaration-sorter --replace --no-map
  

• Sort SCSS files:

  postcss ./src/**/*.scss --syntax postcss-scss --use css-declaration-sorter --replace --no-map
  

• Using the SMACSS order for SCSS files: Add the following configuration to package.json:

  "postcss": {
    "syntax": "postcss-scss",
    "map": false,
    "plugins": {
      "css-declaration-sorter": { "order": "smacss" }
    }
  }
  

  Then run:

  postcss ./src/**/*.scss --replace --config package.json
  

JavaScript Usage

Here's how to apply the sorter in a vanilla JavaScript setup:

import postcss from 'postcss';
import { cssDeclarationSorter } from 'css-declaration-sorter';

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

API Options

• Order: Specify one of the built-in orders — alphabetical, smacss, or concentric-css — or define a custom sorting function.
• Keep Overrides: Setting this to true preserves the order of shorthand and longhand property declarations, including vendor prefixes. This is beneficial for maintaining CSS compatibility.

For more use cases and examples, check out the examples section of the project repository.