Incremental build cache

Reuse one cache instance

Keep one instance alive for a watch loop, build server, or repeated programmatic compilation. A new in-memory instance starts cold.

import { readFile } from "node:fs/promises";
import { createIncrementalBuildCache } from "@coordiation/css";

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

console.log(scan.cache);
console.log(result.cache);

Use persistent CLI caching

One-shot and watch builds use .coordiation-cache/coordiation-css-v1.json by default. The directory is excluded from source discovery.

coordiation-css \
  --input src/coordiation.css \
  --output dist/coordiation.css \
  --content src \
  --cache-dir .coordiation-cache

Use --no-cache for a deliberate cold-build comparison or a read-only environment. Cache writes use a temporary sibling file and atomic rename.

Let adapters own their process cache

The official Vite and PostCSS adapters create one in-memory cache per plugin instance. Their existing watcher and dependency messages remain the invalidation boundary.

coordiation({
  content: ["src"],
  cssFile: "src/coordiation.css",
  cache: true,
})

Set cache: false only when profiling cold behavior or when a host intentionally owns caching.

Inspect every cache decision

Scanner and compiler results expose compact JSON-safe manifests for logs, tests, and AI tooling.

scan.cache = {
  enabled: true,
  persistent: true,
  hits: 14,
  misses: 1,
  removed: 0,
  fingerprint: "…"
}

result.cache = {
  enabled: true,
  persistent: true,
  hit: false,
  key: "…"
}

A scan hit means extraction was reused. A compiler hit means the final compiled result was reused. Neither status changes whether a candidate is supported.