postcss-ordered-values

postcss-ordered-values is a PostCSS plugin that ensures CSS property values are consistently ordered. It normalizes properties that accept values in arbitrary order (such as border, animation, transition, etc.) to make it easier for other CSS optimization tools to identify duplicate declarations and improve compression.

Package Information

• Package Name: postcss-ordered-values
• Package Type: npm
• Language: JavaScript
• Installation: npm install postcss-ordered-values

Core Imports

const orderedValues = require('postcss-ordered-values');

For TypeScript:

import orderedValues = require('postcss-ordered-values');
// or
const orderedValues = require('postcss-ordered-values');

Basic Usage

const postcss = require('postcss');
const orderedValues = require('postcss-ordered-values');

// Process CSS with the plugin
const result = postcss([orderedValues()])
  .process(css, { from: undefined });

console.log(result.css);

Input CSS:

h1 {
  border: solid 1px red;
  border: red solid .5em;
  border: rgba(0, 30, 105, 0.8) solid 1px;
  border: 1px solid red;
}

Output CSS:

h1 {
  border: 1px solid red;
  border: .5em solid red;
  border: 1px solid rgba(0, 30, 105, 0.8);
  border: 1px solid red;
}

Additional Examples:

// Animation property normalization
const css1 = 'div { animation: bounce infinite 2s ease-in-out; }';
// Result: div { animation: bounce 2s ease-in-out infinite; }

// Box shadow with inset
const css2 = 'div { box-shadow: red 10px 10px inset; }';
// Result: div { box-shadow: inset 10px 10px red; }

// Flex flow ordering
const css3 = 'div { flex-flow: wrap column; }';
// Result: div { flex-flow: column wrap; }

// Grid auto flow
const css4 = 'div { grid-auto-flow: dense row; }';
// Result: div { grid-auto-flow: row dense; }

Architecture

The plugin operates through several key components:

• Plugin Creator: Main export function that returns a PostCSS plugin
• Rule Processors: Specialized functions for different CSS property types
• Value Parser Integration: Uses postcss-value-parser for parsing CSS values
• Caching System: Internal caching to avoid reprocessing identical values
• Vendor Prefix Handling: Normalizes vendor-prefixed properties

Capabilities

Main Plugin Function

Creates a PostCSS plugin that processes CSS declarations to normalize property value order.

/**
 * Creates a PostCSS plugin for ordering CSS property values
 * @returns {Plugin} PostCSS plugin instance
 */
function pluginCreator(): Plugin;

The plugin processes CSS declarations during the OnceExit phase, after all other transformations are complete. It maintains a cache of processed values to improve performance on repeated values.

Supported CSS Properties

The plugin handles the following CSS properties and their vendor-prefixed variants:

Border Properties

• border, border-top, border-right, border-bottom, border-left
• border-block, border-inline, border-block-start, border-block-end
• border-inline-start, border-inline-end
• outline
• column-rule

Normalization Order: <width> <style> <color>

Animation Properties

• animation, -webkit-animation

Normalization Order: <name> <duration> <timing-function> <delay> <iteration-count> <direction> <fill-mode> <play-state>

Box Shadow

• box-shadow

Normalization Order: <inset> <length-values> <color>

Flex Properties

• flex-flow

Normalization Order: <flex-direction> <flex-wrap>

Grid Properties

• grid-auto-flow
• grid-column-gap, grid-row-gap
• grid-column, grid-row
• grid-column-start, grid-column-end
• grid-row-start, grid-row-end

Grid Auto Flow Normalization Order: <row/column> <dense>

Grid Gap Normalization: Normalizes normal keyword to front position when present

List Style

• list-style

Normalization Order: <type> <position> <image>

Transition Properties

• transition, -webkit-transition

Normalization Order: <property> <duration> <timing-function> <delay>

Column Properties

• columns

Normalization Order: <width> <count> (only transforms valid two-value declarations)

Processing Behavior

The plugin includes intelligent processing controls:

• CSS Variable Support: Aborts processing when CSS variables (var(), env(), constant()) are detected
• Comment Preservation: Skips processing when comments are present in values
• Math Function Handling: Recognizes and properly processes CSS math functions (calc(), clamp(), max(), min()) - may abort processing in complex contexts to avoid incorrect transformations
• Vendor Prefix Normalization: Strips vendor prefixes for internal processing while preserving them in output
• Minimal Value Skip: Only processes declarations with 2 or more value nodes

Error Handling

The plugin gracefully handles various edge cases:

• Invalid or malformed CSS values are left unchanged
• CSS Loader imports (___CSS_LOADER_IMPORT___) abort processing
• Complex math functions in certain contexts may abort processing to avoid incorrect transformations

Plugin Properties

// Plugin identifier for PostCSS
pluginCreator.postcss = true;

Types

For TypeScript users, the plugin exports match the actual type definitions:

/**
 * Main plugin creator function exported via CommonJS
 */
declare function pluginCreator(): import("postcss").Plugin;

declare namespace pluginCreator {
  let postcss: true;
}

export = pluginCreator;

Dependencies

• postcss-value-parser: Parses CSS property values into node trees
• cssnano-utils: Provides utility functions for CSS processing

Peer Dependencies

• postcss: PostCSS framework (^8.4.32)