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
| Option | Default | Meaning |
|---|---|---|
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 |
include | none | Your own CSS files, appended unchanged at the end and without a layer, so they win over everything |
output | assets/css/app.css | Where the stylesheet goes (dist/<output> in build, served at /<output> in dev) |
colors | none | Extra semantic color names: bg-dark, text-dark-foreground/85 resolve to var(--dark) |
breakpoints | sm md lg xl 2xl | Add or override breakpoints, for example { "3xl": "120rem" } |
variants | none | Custom variants: { "pwa": { "rank": "arbitrary", "at": "@media (display-mode: standalone)" } }. sels takes selector templates with & |
safelist | none | Classes to emit even if no file contains them (names built by concatenation are invisible to the scan) |
minify | true in chroma build, false in chroma dev | Minified output has no comments and no layout whitespace |
tokens, base | true | Set 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).
Related
- Utilities and generator: grammar and variants
- Styling: the whole styling story of a Chroma app
- Targ Apps styles: a complete site that uses it