eslint-plugin-css-property-order

v1.0.0

Published

17 days ago

ESLint plugin enforcing CSS declaration order for @eslint/css: Recess/Bootstrap logical order, Chrome DevTools panel order, or your own.

0High
0Medium
0Low

dmnsgn

eslint eslintplugin eslint-plugin css property-order declaration-order properties-order recess devtools stylelint-order

eslint-plugin-css-property-order

ESLint plugin enforcing CSS declaration order for @eslint/css: Recess/Bootstrap logical order, Chrome DevTools panel order, alphabetical, or your own. Autofixable. Includes processors to lint and fix CSS embedded in HTML <style> tags and in /* css */-annotated or css-tagged template literals.

Installation

npm install -D eslint-plugin-css-property-order @eslint/css

Usage

// eslint.config.js
import { defineConfig } from "eslint/config";
import css from "@eslint/css";
import cssPropertyOrder from "eslint-plugin-css-property-order";

export default defineConfig([
  {
    files: ["**/*.css"],
    plugins: { css },
    language: "css/css",
    extends: [cssPropertyOrder.configs.recommended],
  },
]);

[!NOTE] Use extends (or a separate config object) rather than spreading configs.recommended into an object that also declares plugins: the spread would replace the plugins key, unregistering the css plugin that language: "css/css" refers to.

Run eslint --fix to reorder declarations automatically.

Built-in orders

"recess" (default, used by configs.recommended): the Recess/Bootstrap "logical" order — positioning, box model, typography, visual, animation, misc. Snapshot of stylelint-config-recess-order.
"devtools" (used by configs.devtools): the order Chrome DevTools shows in the Computed panel's grouped view — Layout, Text, Appearance, Animation, Grid, Table, Generated Content — generated from the DevTools sources themselves (PropertyNameCategories.ts + Blink's property metadata).
"alphabetical" (used by configs.alphabetical): plain alphabetical order. No property list is involved — names are compared directly, so every CSS property (present and future, standard or not) is covered and the unspecified option does not apply. Vendor-prefixed properties sort right before their unprefixed counterpart (-webkit-transform before transform), the order the cascade requires for fallbacks; custom properties are alphabetized at the top.

Options

{
  files: ["**/*.css"],
  plugins: { css, "css-property-order": cssPropertyOrder },
  language: "css/css",
  rules: {
    "css-property-order/property-order": [
      "error",
      {
        // "recess", "devtools", or an array of property names and/or
        // { properties: [...] } groups:
        order: "recess",
        // Where properties absent from the order belong — "ignore" (leave
        // them where they are), "top", "bottom", or "bottomAlphabetical".
        // New CSS properties degrade gracefully: they are simply unspecified
        // until the order lists them.
        unspecified: "ignore",
        // Custom properties (--*) must come first ("top", default) or are
        // left alone ("ignore"). Their relative order is preserved.
        customProperties: "top",
      },
    ],
  },
}

Embedded CSS: HTML `<style>` tags and template literals

@eslint/css only lints .css files (HTML support is "not planned"). This plugin bridges the gap with two ESLint processors that extract embedded CSS into virtual *.css files — so your whole files: ["**/*.css"] config applies to them, every @eslint/css rule included, with autofix mapped back into the host file:

// eslint.config.js
export default defineConfig([
  // Your CSS config lints the extracted blocks too:
  {
    files: ["**/*.css"],
    plugins: { css },
    language: "css/css",
    extends: [cssPropertyOrder.configs.recommended],
  },
  // <style> tags in HTML files:
  {
    files: ["**/*.html"],
    plugins: { "css-property-order": cssPropertyOrder },
    processor: "css-property-order/html",
  },
  // /* css */ `…` and css`…` template literals in JS/TS files:
  {
    files: ["**/*.js"],
    plugins: { "css-property-order": cssPropertyOrder },
    processor: "css-property-order/tagged-template",
  },
]);

Both processors have factories for options (import them from the package):

createTaggedTemplateProcessor({ tags: ["css"], emitSource: true }) — tags sets which template tags mark CSS (the /* css */ comment form is always recognised); emitSource (default on) re-emits the JS/TS source so regular JavaScript linting keeps running on the file.
createHtmlProcessor({ emitSource: false }) — enable emitSource only if something else handles your HTML files — an HTML language config (e.g. html-eslint) or eslint-plugin-html for <script> linting — so it keeps linting them; without one the re-emitted source would be parsed as JavaScript.

Extraction limits (by design): template literals containing ${} substitutions or backslash escapes are skipped (their runtime value differs from the source, so fixes could not be mapped safely); HTML extraction is regex-based and ignores <style> inside comments and scripts; type-aware TypeScript linting does not work on processor virtual files (an ESLint-wide limitation).

Behavior notes

Declarations are only reordered within a contiguous run: nested rules and at-rules act as boundaries, so a fix never moves a declaration across a nested rule (which could change the cascade).
Comments are left in place; declarations move around them.
Matching is case-insensitive; duplicate properties keep their relative order.

Updating the built-in orders

npm run generate:refresh re-downloads the DevTools sources (vendored in vendor/, provenance recorded in the generated files) and re-snapshots the Recess order, so newly shipped CSS properties flow into src/orders/.

npm run report:w3c compares the list-based presets against the official W3C CSS property index and reports which specified properties they do not list (those fall back to the unspecified option at lint time). The index spans every spec at every maturity level, so the report is informational — presets are never amended from it.