TOOLING · COMPLETE

CSS toolchain

Turn one CSS entry into production-ready static output with local import bundling, native nesting transforms, explicit browser-target prefixing, and optional minification.

✓

Vite, PostCSS, and the CLI use this pipeline by default. Every result declares its exact stages, targets, imported files, and warnings in a JSON-safe toolchain manifest.

PIPELINE ORDER

One entry, two controlled transform phases

Ordering is fixed so project directives and authored CSS share the same predictable result.

01
Bundle: resolve local @import paths relative to the entry filename.
02
Compile: resolve theme, custom utilities, variants, plugins, scanned candidates, and Preflight.
03
Transform: lower nesting and add only prefixes required by the configured browser targets.
04
Optimize: minify only when explicitly enabled for production output.

Split CSS without losing framework context

Imported theme directives, custom utilities, and authored styles are bundled before candidate compilation. Paths stay literal and relative to the entry file.

src/coordiation.css

@import "./theme.css";
@import "./components.css";
@coordiation;

.dashboard {
  container-type: inline-size;
}

src/theme.css

@co-theme {
  --co-color-surface: oklch(98% 0 0);
  --co-radius-card: 1rem;
}

Imported files become first-class dependencies: Vite watches and hot-updates them, PostCSS emits dependency messages, and CLI watch mode fingerprints their contents.

Author native nested CSS

Nesting is lowered after Coordiation has emitted generated and authored CSS. The output remains ordinary browser CSS with no runtime parser.

Input

.card {
  color: var(--co-color-neutral-900);

  & > .title {
    font-weight: 700;
  }
}

Conceptual output

.card {
  color: var(--co-color-neutral-900);
}

.card > .title {
  font-weight: 700;
}

Make browser support explicit

Prefixing is derived from named targets rather than an opaque environment default. The shipped baseline is Chrome 111, Edge 111, Firefox 113, Safari 15.4, and iOS Safari 15.4.

JavaScript

const result = await compileWithToolchain(inputCss, candidates, {
  filename: "/project/src/coordiation.css",
  toolchain: {
    targets: {
      chrome: "111",
      firefox: "113",
      safari: "15.4",
      ios_saf: "15.4",
    },
  },
});

Single ownership

If another named tool must own nesting or prefixing, disable only that Coordiation stage. Avoid running two prefixers over the same output.

Minify production builds deliberately

Readable CSS is the default for development and inspection. Enable minification in the production configuration or pass --minify to the CLI.

vite.config.js

coordiation({
  content: ["src"],
  cssFile: "src/coordiation.css",
  toolchain: {
    minify: process.env.NODE_ENV === "production",
  },
})

CLI

coordiation-css \
  --input src/coordiation.css \
  --output dist/coordiation.css \
  --content src \
  --minify \
  --target chrome=111 \
  --target safari=15.4

Use the asynchronous build API

compileWithToolchain() is the production entry point. Supply a real filename whenever imports are enabled so relative resolution and diagnostics remain deterministic.

build.mjs

import { readFile } from "node:fs/promises";
import { compileWithToolchain, scanSources } from "@coordiation/css";

const filename = "/project/src/coordiation.css";
const inputCss = await readFile(filename, "utf8");
const scan = await scanSources(["/project/src"]);
const result = await compileWithToolchain(inputCss, scan.candidates, {
  filename,
  toolchain: { minify: true },
});

console.log(result.css);
console.log(result.toolchain);

Use synchronous compile() only when the host intentionally owns import resolution and all CSS transformations.

OPTIONS

Disable stages independently

toolchain: false disables all four stages. An object changes only the named settings.

01
imports: defaults to true; set false or use --no-imports to preserve imports.
02
nesting: defaults to true; set false or use --no-nesting to preserve native nesting.
03
prefixing: defaults to true; set false or use --no-prefixing when another tool owns it.
04
minify: defaults to false; set true or use --minify for compact output.
05
targets: a browser-to-version object, or repeatable CLI --target browser=version values.

Track the effective build contract

The manifest is designed for build tools, diagnostics, and coding agents. Runtime functions never appear in it.

result.toolchain

{
  engine: "lightningcss",
  engineVersion: "1.33.0",
  imports: true,
  nesting: true,
  prefixing: true,
  minify: false,
  targets: { chrome: "111", safari: "15.4" },
  files: ["/project/src/theme.css"],
  warnings: []
}

BOUNDARIES

Keep ownership and claims precise

The toolchain fails the current build when an import or transformation cannot be completed.

Use local resolvable import paths and a real entry filename.
Do not run a second nesting transform or prefixer unless the matching Coordiation stage is disabled.
Keep development output readable and enable minification intentionally for production.
Read toolchain.files instead of constructing a separate import dependency graph.
Enable sourceMap when the consumer can retain the native framework map.

AI GENERATION CONTRACT

Inspect before generating configuration

Agents should make the build stages observable, not infer them from a package name.

Prefer compileWithToolchain() for new build integrations.
Keep import paths and CLI targets literal and auditable.
Match the manifest targets before explaining browser compatibility.
Use imported dependency paths from the manifest for watchers and caches.
Report toolchain errors or warnings instead of returning partially transformed CSS.

Previous← Plugin API NextIncremental cache →