@teacss/cli

The teacss-cli command: scan source files and generate CSS, with watch mode.

npm install --save-dev @teacss/cli @teacss/preset-standard
npx teacss-cli "src/**/*.{ts,tsx,html}" -o tea.css
npx teacss-cli "src/**/*.{ts,tsx,html}" -o tea.css --watch
npx teacss-cli --check

Use the equivalent local-binary command for pnpm, Yarn, or Bun. Run teacss-cli --help for all options. Install every preset package the CSS entry names; @presets "standard,icons,official" needs @teacss/preset-standard, @teacss/preset-icons and @teacss/preset-official.

A pattern's wildcards, and a pattern that names a directory, never walk into node_modules or .git. To scan files there, name the path, such as "node_modules/pkg/*.html".

Matched CSS files are merged into the output. The current output, the -o path or tea.css with --stdout, is never read back. An output whose merged CSS carries a TeaCSS directive ends with a /* teacss-cli output <hash> */ seal, and every run skips a matched file whose seal is intact. An output without directives has no seal, so an old one at any other matched path is read as a source. Write outputs outside the patterns, or delete old ones.

Without a CSS entry, the standalone command needs only this package:

npx teacss-cli "src/**/*.{ts,tsx,html}" --preset standard -o tea.css

Configuration comes from index.css, src/index.css, or package.json#teacss.entry:

@presets "standard";
@source "./src/**/*.{ts,tsx,html}";
@teacss;

The CLI never selects a preset implicitly. Without a CSS entry, pass --preset standard. --check prints the resolved project, entry, presets, sources, rules, and shortcuts without writing CSS.

Source transformers may produce an empty file; its original classes then emit no utilities. --rewrite writes that empty result back to the source, while normal generation leaves the source file intact.

Programmatic watch

import { build } from "@teacss/cli";

const session = await build({
  patterns: ["src/**/*.{ts,tsx,html}"],
  outFile: "tea.css",
  watch: true,
});

await session.dispose();

Each session owns its watcher. Disposal cancels queued builds and waits for active work. Recoverable watch errors are reported without changing the host process exit code; startup failures still set the CLI exit status.

Use a build adapter when another tool owns the module graph. Class sorting is editor-owned, not a CLI command.

Pre-1.0.

Watch mode reloads source-scanned @shortcut and @safelist declarations when matched CSS is added, changed, removed, or recreated, including external absolute sources and initially missing source roots. CLI entry patterns still determine which files contribute extracted utility tokens. A bounded declaration check every 500 ms also recovers changes omitted by native callbacks; unchanged declarations do not reload configuration or rebuild.

Glob-matched CSS file symlinks observe their physical file targets through filtered shallow parent watches, including recovery after a failed member read. Nested source directory symlinks observe physical target changes, including empty targets and target deletion or recreation. Missing routes use shallow parent observation. Failed reads retain the last accepted configuration.