.. | ||
lib | ||
node_modules | ||
CHANGELOG.md | ||
index.js | ||
LICENSE.md | ||
package.json | ||
README.md |
PostCSS Sorting
![npm downloads last month](https://img.shields.io/npm/dm/postcss-sorting.svg)
PostCSS plugin to keep rules and at-rules content in order.
Also available as Sublime Text, Atom, VS Code, and Emacs plugin.
Lint and autofix 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.
- Supports CSS, SCSS (using postcss-scss), HTML (with postcss-html), CSS-in-JS (with postcss-jsx), 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
: 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 inproperties-order
.throw-validate-errors
: Throw config validation errors instead of just showing and ignoring them. Defaults tofalse
.
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 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;
}
`;
Migration from 2.x
Remove all *-empty-line-before
and clean-empty-lines
options. Use stylelint with --fix
option instead.
properties-order
doesn't support property groups. Convert it to simple array. Use stylelint-order with --fix
option for empty line before property groups.
Config for 2.x
:
{
"properties-order": [
{
"properties": [
"margin",
"padding"
]
},
{
"emptyLineBefore": true,
"properties": [
"border",
"background"
]
}
]
}
Config for 3.x
:
{
"properties-order": [
"margin",
"padding",
"border",
"background"
]
}
Usage
See PostCSS docs for examples for your environment.
Text editor
This plugin available as Sublime Text, Atom, VS Code, and Emacs 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'
}
}
});
Command Line
Add postcss-cli and PostCSS Sorting to your project:
npm install postcss-cli postcss-sorting --save-dev
Create an appropriate postcss.config.js
like this example:
module.exports = (ctx) => ({
plugins: {
'postcss-sorting': {
'order': [
'custom-properties',
'dollar-variables',
'declarations',
'at-rules',
'rules'
],
'properties-order': 'alphabetical',
'unspecified-properties-position': 'bottom'
}
}
})
Or, simply add the 'postcss-sorting'
section to your existing postcss-cli configuration file. Next, execute:
postcss -c postcss.config.js --no-map -r your_css_file.css
For more information and options, please consult the postcss-cli docs.
Related tools
stylelint and stylelint-order help lint style sheets and let you know if style sheet order is correct. Also, they could autofix style sheets.
I recommend Prettier for formatting style sheets.