postcss-custom-prop-sorting

Bring together all custom properties at the top of a set of rules and sort them by a provided sorting function (defaults to alphanumeric).

Installation

1yarn add -D postcss-custom-prop-sorting

Usage

1postcss -u postcss-custom-prop-sorting -o dist/index.css src/index.css

This plugin turns this:

1.lightest {
2  text-transform: capitalize;
3  --a: var(--e);
4  color: var(--e);
5  --b3: rgba(255, 255, 255, 0.8);
6  --b10: rgba(255, 255, 255, 0.3);
7  --b200: rgba(255, 255, 255, 0.5);
8  --d: block;
9  display: var(--d);
10  --e: #fff;
11  --c: 10px;
12  font-size: var(--c, 18px);
13}

Into this:

1.lightest {
2  --b3: rgba(255, 255, 255, 0.8);
3  --b10: rgba(255, 255, 255, 0.3);
4  --b200: rgba(255, 255, 255, 0.5);
5  --c: 10px;
6  --d: block;
7  --e: #fff;
8  --a: var(--e);
9
10  text-transform: capitalize;
11  color: var(--e);
12  display: var(--d);
13  font-size: var(--c, 18px);
14}

You can optionally provide your own custom sorting logic that is keyed on either the property name or any value available in the Declaration object. The example below shows an alphabetizing logic based on the values.

1  postcss.process([
2    require("postcss-custom-prop-sorting")({
3      sortOrder: ([aProp, aDecl], [bProp, bDecl]) => {
4        /* Sort by value. */
5        const aValue = aDecl.value;
6        const bValue = bDecl.value;
7        return (aValue > bValue ? 1 : -1);
8      },
9    })
10  ])

Running this against the same input above, we would now get:

1.lightest {
2  --e: #fff;
3  --c: 10px;
4  --d: block;
5  --b10: rgba(255, 255, 255, 0.3);
6  --b200: rgba(255, 255, 255, 0.5);
7  --b3: rgba(255, 255, 255, 0.8);
8  --a: var(--e);
9
10  text-transform: capitalize;
11  color: var(--e);
12  display: var(--d);
13  font-size: var(--c, 18px);
14}

You could use this to sort custom properties for example by type, parsing values by leveraging the postcss-value-parser.

or implement a manual logic similar to how the css-declaration-sorter project does and define your logic manually.

Important note, if custom properties have internal dependencies to other custom properties in the same rule, those dependencies will not be sorted, rather, they will be injected at the end of the list so as not to alter their resolutions.

Options

sortOrder

Type: ([string, Declaration], [string, Declaration]) => Number
Default: ([a], [b]) => a.localeCompare(b, undefined, { numeric: true }),

A custom function can be passed to the array sort method. That function will receive two arrays, each containing the property name (including the -- prefix) and the corresponding Declaration object. The function should return a number, where a negative number indicates that the first item should be sorted before the second, a positive number indicates that the second item should be sorted before the first, and zero indicates that the items are equal.