burner03 / postcss-sorting

PostCSS plugin to keep rules and at-rules content in order.

PostCSS Sorting

PostCSS plugin to keep rules and at-rules content in order.

Also available as Sublime Text plugin, Atom plugin, and VS Code plugin.

Lint style sheets 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.
• Adds empty lines before different types of nodes.
• Supports CSS, SCSS (if postcss-scss parser is used), PreCSS and most likely any other syntax added by other PostCSS plugins.

Installation

$ npm install postcss-sorting

Options

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

Order

• order: Specify the order of content within declaration blocks.
• properties-order: Specify the order of properties within declaration blocks. Can specify empty line before property groups.
• unspecified-properties-position: Specify position for properties not specified in properties-order.

Empty lines

• clean-empty-lines: Remove all empty lines. Runs before all other rules.
• rule-nested-empty-line-before: Specify an empty line before nested rules.
• at-rule-nested-empty-line-before: Specify an empty line before nested at-rules.
• declaration-empty-line-before: Specify an empty line before declarations.
• custom-property-empty-line-before: Specify an empty line before custom properties.
• dollar-variable-empty-line-before: Specify an empty line before $-variable declarations.
• comment-empty-line-before: Specify an empty line before comments.

Handling comments

Shared-line comments are comments which are located after a node and on the same line as a node.

a {
	/* regular comment */
	color: pink; /* shared-line comment */
}

Shared-line comments are always ignored in all “empty lines before” options. The plugin always looks “through” these comments. For example:

{
	"declaration-empty-line-before": [true, {
		except: "after-declaration"
	}]
}

Technically there is a comment before bottom. But it's a shared line comment, so plugin looks before this comment and sees top:

a {
	--prop: pink;

	top: 5px; /* shared-line comment */
	bottom: 15px;
}

For “order” options comments that are before node and on a separate line linked to that node. Shared-line comments are also linked to that 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` */
}

Migration from 1.x

If you have been using predefined configs, you can look at migrated predefined configs.

sort-order was split into order and properties-order.

properties-order now uses an array of objects for grouping.

sort-order keywords to new config conversion:

1.x	2.x
@atrule	{ order: ["at-rules"] } or { order: [{ type: "at-rule" }] }
@atrulename	{ order: [{ type: "at-rule", name: "atrulename" }] }
@atrulename parameter	{ order: [{ type: "at-rule", name: "atrulename", parameter: "parameter" }] }
>child	{ order: ["rules"] }
$variable	{ order: ["custom-properties", "dollar-variables"] }
“leftovers” token ...	{ "unspecified-properties-position": "bottom" }

Config for 1.x:

{
	"sort-order": [
		[
			"$variable"
		],
		[
			"margin",
			"padding"
		],
		[
			"border",
			"background"
		],
		[
			'...',
			"at-rule",
			"@include",
			"@include media",
			">child"
		]
	]
}

Config for 2.x:

{
	"order": [
		"custom-properties",
		"dollar-variables",
		"declarations",
		"at-rules",
		{
			"type": "at-rule",
			"name": "include"
		},
		{
			"type": "at-rule",
			"name": "include",
			"parameter": "icon"
		},
		"rules"
	],
	"properties-order": [
		{
			"emptyLineBefore": true,
			"properties": [
				"margin",
				"padding"
			]
		},
		{
			"emptyLineBefore": true,
			"properties": [
				"border",
				"background"
			]
		}
	],
	"unspecified-properties-position": "bottom"
}

Usage

See PostCSS docs for examples for your environment.

Text editor

This plugin available as Sublime Text plugin, Atom plugin, and VS Code plugin.

Gulp

Add Gulp PostCSS and PostCSS Sorting to your build tool:

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

Enable PostCSS Sorting within your Gulpfile:

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

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

Grunt

Add Grunt PostCSS and PostCSS Sorting to your build tool:

npm install grunt-postcss postcss-sorting --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'
		}
	}
});

Related tools

stylelint and stylelint-order help lint style sheets and let know if style sheet order is correct.

If you want format style sheets, use perfectionist or stylefmt, also a PostCSS-based tools.

Thanks

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