Targ Apps Docs

chroma-style (build plugin)

The native utility-CSS generator of the Chroma CLI: scans classes in your sources and writes one layered stylesheet. Options, output, dev behavior and what it replaces.

chroma-style reads the class names your code uses and writes one stylesheet with exactly those rules, in cascade layers, followed by your own CSS. It is the generator that used to be tools/build.mjs (and scripts/css.mjs plus a watcher in every project), now compiled into the CLI. The grammar is the one documented in Utilities and generator; the design tokens, tw() and the cva presets stay in the Chroma-Style runtime plugin.

Turn it on

{
  "plugins": ["chroma-style"],
  "pluginOptions": {
    "chroma-style": {
      "src": ["src", "index.html"],
      "include": ["src/styles/tokens.css", "src/styles/base.css", "src/styles/layout.css"],
      "colors": ["dark", "dark-foreground"]
    }
  }
}
<link rel="stylesheet" href="/assets/css/app.css">

The generator runs only when pluginOptions.chroma-style exists ({} is enough), so the chroma-style entry that every template has for the runtime plugin does not produce a stylesheet by itself.

Options

OptionDefaultMeaning
src["src", "index.html"]Files or folders to scan for class names (.chr, .html, .js, .ts, .md, .mdx, .vue, .svelte…). node_modules, .git, dist, pkg, .chroma and reference folders are skipped
includenoneYour own CSS files, appended unchanged at the end and without a layer, so they win over everything
outputassets/css/app.cssWhere the stylesheet goes (dist/<output> in build, served at /<output> in dev)
colorsnoneExtra semantic color names: bg-dark, text-dark-foreground/85 resolve to var(--dark)
breakpointssm md lg xl 2xlAdd or override breakpoints, for example { "3xl": "120rem" }
variantsnoneCustom variants: { "pwa": { "rank": "arbitrary", "at": "@media (display-mode: standalone)" } }. sels takes selector templates with &
safelistnoneClasses to emit even if no file contains them (names built by concatenation are invisible to the scan)
minifytrue in chroma build, false in chroma devMinified output has no comments and no layout whitespace
tokens, basetrueSet to false to leave the tokens or base layer out

chroma-style.config.mjs is gone: its colors, breakpoints, safelist and variants are options now. Custom utility functions (utilities in the old config) were JavaScript and are not supported; use arbitrary values (w-[13.5rem], [mask-type:alpha]) or an include file.

What it writes

@layer tokens, base, components, utilities;
tokens      tokens.css of Chroma-Style, plus the palette variables (--color-red-500) that are used
base        reset and base styles
components  prose and cs-* sections, only the ones whose class is used, plus the @keyframes that are referenced
utilities   the utilities your code uses, with their variants ordered so the right rule wins
@property   the internal --cs-* variables that need an initial value
your CSS    every file of "include"

The CSS layers (tokens.css, base.css, prose.css, components.css, animate.css) are embedded in the plugin; they are the files of the Chroma-Style package.

In chroma dev

The stylesheet is generated in memory and served at /<output>. A change to a scanned file, to an include file or to chroma.json regenerates it before the page reloads, so a new class works as soon as you save. Files produced by other plugins (src/data/blog.chr) are scanned too, because their HTML contains classes.

Parity

On the Targ Apps site the generator finds 857 classes and emits 867 rules; both the minified and the expanded output are byte-identical to what the Node generator wrote. The tests also compare a fixture that exercises most utility and variant families (arbitrary values, calc() spacing, group-*, peer-*, has-*, data-*, container queries, prose) and regenerate the starter utilities.css of Chroma-Style. Sorting of equal-priority rules follows Intl.Collator with numeric ordering, so p-2 precedes p-10.

Explain a class

cargo run -p chroma-plugins --example style_explain -- explain "md:hover:bg-primary/80"

prints the CSS of one class (run it in the Chroma-Compiler workspace).

On this page