Automating Layer Order with PostCSS and Vite

// layers.config.js — the ONLY place the canonical order is written.
// WHY: a single export feeds the PostCSS injector, the CI validator, and
// the Stylelint allowlist, so those three can never drift out of sync.
export const LAYERS = ["reset", "base", "themes", "components", "utilities", "overrides"];
export const MANIFEST = `@layer ${LAYERS.join(", ")};`;

/* src/styles/layers.css — generated to match MANIFEST, imported first.
   WHY: contains ONLY the name declaration, no rules, so re-declaring it in
   other chunks is idempotent and free of cascade side effects. */
@layer reset, base, themes, components, utilities, overrides;

// postcss-layer-manifest.js
import { LAYERS } from "./layers.config.js";
const CANONICAL = LAYERS.join(", ");

// WHY: prepend the manifest so the canonical order is registered before any
// rule in THIS file — the browser locks layer order at first sight.
const plugin = () => ({
  postcssPlugin: "layer-manifest",
  Once(root, { AtRule }) {
    const first = root.first;
    const present =
      first?.type === "atrule" &&
      first.name === "layer" &&
      first.params.replace(/\s+/g, " ").trim() === CANONICAL;
    if (!present) root.prepend(new AtRule({ name: "layer", params: CANONICAL }));
  },
});
plugin.postcss = true;
export default plugin;

// postcss.config.js
import postcssImport from "postcss-import";
import layerManifest from "./postcss-layer-manifest.js";
import cascadeLayers from "@csstools/postcss-cascade-layers";

export default {
  plugins: [
    postcssImport(),   // WHY: inline @imports FIRST so no unlayered import sneaks above the manifest
    layerManifest(),   // WHY: then guarantee the canonical order leads the file
    cascadeLayers(),   // WHY: polyfill LAST so it sees the full, ordered layer set (drop when unneeded)
  ],
};

// vite.config.js
import { defineConfig } from "vite";
import layerManifest from "./postcss-layer-manifest.js";

export default defineConfig({
  css: {
    // WHY: run the injector per emitted chunk so a code-split route's stylesheet
    // still registers the canonical order first in production.
    postcss: { plugins: [layerManifest()] },
  },
});

// src/main.js — layers.css MUST be the first CSS side-effect import.
// WHY: in the dev server Vite serves CSS in import order; importing the
// manifest first registers the order before any component style is injected.
import "./styles/layers.css";
import "./styles/reset.css";
import "./styles/components.css";
import { mountApp } from "./app.js";
mountApp();

// scripts/validate-layer-order.mjs
import { readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { MANIFEST } from "../layers.config.js";

const DIST = "dist/assets";
// WHY: match the FIRST @layer statement in each emitted file; it must equal
// the canonical manifest or the browser could register a rival order first.
const firstLayer = /@layer[^;{]*;/;
let failed = false;

for (const file of readdirSync(DIST).filter((f) => f.endsWith(".css"))) {
  const css = readFileSync(join(DIST, file), "utf8");
  const match = css.match(firstLayer);
  const found = match?.[0].replace(/\s+/g, " ").trim();
  if (found !== MANIFEST) {
    console.error(`✗ ${file}: expected "${MANIFEST}" but found "${found ?? "none"}"`);
    failed = true;
  }
}
if (failed) process.exit(1);
console.log("✓ every emitted stylesheet leads with the canonical layer order");

# WHY: build first so the script inspects real emitted chunks, then lint source.
npm run build && node scripts/validate-layer-order.mjs && npx stylelint "src/**/*.css" --max-warnings 0

// layers.config.js
export const LAYERS = ["reset", "base", "themes", "components", "utilities", "overrides"];
export const MANIFEST = `@layer ${LAYERS.join(", ")};`;

// postcss-layer-manifest.js
import { LAYERS } from "./layers.config.js";
const CANONICAL = LAYERS.join(", ");
const plugin = () => ({
  postcssPlugin: "layer-manifest",
  Once(root, { AtRule }) {
    const f = root.first;
    const present =
      f?.type === "atrule" && f.name === "layer" &&
      f.params.replace(/\s+/g, " ").trim() === CANONICAL;
    if (!present) root.prepend(new AtRule({ name: "layer", params: CANONICAL }));
  },
});
plugin.postcss = true;
export default plugin;

// postcss.config.js
import postcssImport from "postcss-import";
import layerManifest from "./postcss-layer-manifest.js";
import cascadeLayers from "@csstools/postcss-cascade-layers";
export default {
  // Order is load-bearing: inline, then inject, then polyfill.
  plugins: [postcssImport(), layerManifest(), cascadeLayers()],
};

// vite.config.js
import { defineConfig } from "vite";
import layerManifest from "./postcss-layer-manifest.js";
export default defineConfig({
  css: { postcss: { plugins: [layerManifest()] } },
});

/* src/styles/layers.css — imported first in src/main.js */
@layer reset, base, themes, components, utilities, overrides;

# package.json script: "verify:layers"
npm run build \
  && node scripts/validate-layer-order.mjs \
  && npx stylelint "src/**/*.css" --max-warnings 0