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 keep rules and at-rules content in order.

Lint and autofix stylesheet order with stylelint-order.

Features

• Sorts rules and at-rules content.
• Sorts properties.
• Sorts at-rules by different options.
• Groups properties, custom properties, dollar variables, nested rules, nested at-rules.
• Supports CSS, SCSS (using postcss-scss), CSS-in-JS (with @stylelint/postcss-css-in-js), HTML (with postcss-html), and most likely any other syntax added by other PostCSS plugins.

Installation

npm install --save-dev postcss postcss-sorting

Options

The plugin has no default options. Everything is disabled by default.

• order: Specify the order of content within declaration blocks.
• properties-order: Specify the order of properties within declaration blocks.
• unspecified-properties-position: Specify position for properties not specified in properties-order.
• throw-validate-errors: Throw config validation errors instead of showing and ignoring them. Defaults to false.

Caveats

Handling comments

Comments that are before node and on a separate line linked to that node. Shared-line comments are also linked to that node. Shared-line comments are comments which are located after a node and on the same line as a node.

a {
	top: 5px; /* shared-line comment belongs to `top` */
	/* comment belongs to `bottom` */
	/* comment belongs to `bottom` */
	bottom: 15px; /* shared-line comment belongs to `bottom` */
}

Ignored at-rules

Some at-rules, like control and function directives in Sass, are ignored. It means rules won't touch content inside these at-rules, as doing so could change or break functionality.

CSS-in-JS

Plugin will ignore rules, which have template literal interpolation, to avoid breaking the logic:

const Component = styled.div`
	/* The following properties WILL NOT be sorted, because interpolation is on properties level */
	z-index: 1;
	top: 1px;
	${props => props.great && 'color: red'};
	position: absolute;
	display: block;

	div {
		/* The following properties WILL be sorted, because interpolation for property value only */
		z-index: 2;
		position: static;
		top: ${2 + 10}px;
		display: inline-block;
	}
`;

Usage

See PostCSS docs for more examples.

Command Line

Add postcss-cli and PostCSS Sorting to your project:

npm install postcss postcss-cli postcss-sorting --save-dev

Create a postcss.config.js with PostCSS Sorting configuration:

module.exports = {
	plugins: [
		'postcss-sorting': {
			order: [
				'custom-properties',
				'dollar-variables',
				'declarations',
				'at-rules',
				'rules',
			],

			'properties-order': 'alphabetical',

			'unspecified-properties-position': 'bottom',
		},
	],
};

Or, add the 'postcss-sorting' section to your existing postcss-cli configuration file.

Next execute:

npx postcss --no-map --replace your-css-file.css

For more information and options, please consult the postcss-cli docs.

Gulp

Add gulp-postcss and PostCSS Sorting to your build tool:

npm install postcss gulp-postcss postcss-sorting --save-dev

Enable PostCSS Sorting within your Gulpfile:

let gulp = require('gulp');
let postcss = require('gulp-postcss');
let sorting = require('postcss-sorting');

exports['sort-css'] = () => {
	return gulp
		.src('./css/src/*.css')
		.pipe(
			postcss([
				sorting({
					/* options */
				}),
			])
		)
		.pipe(gulp.dest('./css/src'));
};

Text editor

This plugin available as Sublime Text, Atom, VS Code, and Emacs plugin. Though, seems all these plugins are not maintained.

Related tools

stylelint and stylelint-order help lint stylesheets and let you know if stylesheet order is correct. Also, they could autofix stylesheets.

I recommend Prettier for formatting stylesheets.

Changelog

7.0.1

• Internal refactoring for compatibility with newer stylelint-order version. No public API changes.