Installation

The Astro and Vite adapters run the TeaCSS Rust engine. The standalone teacss command uses the same CSS entry and source globs. This guide covers 0.10.11. Use the commands below for the Rust packages. The separate Storybook installation page ↗ documents the reference implementation.

Install an adapter

Use Node.js 26 or later for TeaCSS. Install teacss and the adapter as development dependencies; add the host framework if the application does not already provide it:

The Astro adapter requires Astro 6 or later; the Vite plugin requires Vite 7 or later. For runtime class composition, separately install @teacss/[email protected] as an application dependency. It owns cn, recipe, and their types; the teacss root does not export them. Other supported adapters include @teacss/rsbuild, @teacss/postcss, and @teacss/bun; their package READMEs own the host-specific steps.

Create the CSS entry

Put this at the project-root index.css:

@presets "standard,icons,official";
@source "./src/**/*.{astro,html,js,jsx,ts,tsx}";
@teacss;

@presets opts into comma-separated vocabularies. Standard supplies atomic rules, conditions, theme variables, and preflight; Icons and Official are independent groups. Start with all three and remove unused groups explicitly. @source identifies files that contain complete class tokens, including packages whose markup uses utilities. @teacss inserts the generated CSS. A missing source path can leave visible classes with no emitted rules.

Standard emits theme variables on demand. If authored CSS or inline styles read variables outside utility classes, enable full preflight in the adapter:

import { teacss } from "@teacss/astro";

const integration = teacss({ presetOptions: { standard: { preflight: true } } });

Keep the built-in preset names in @presets; the engine does not load local JavaScript or TypeScript preset modules.

Globs are relative to the CSS entry. If the entry is src/index.css, write @source "./**/*.{astro,html,js,jsx,ts,tsx}"; instead. Entry discovery checks package.json#teacss.entry, then index.css, then src/index.css. A conventional entry must contain a top-level empty @teacss; directive.

Use the entry to bind a palette to a site color alias:

@presets "standard";
@custom office "indigo";
@teacss;

This enables bg-color:office-900. For component colors, see Palette. There is no teacss.config.* file or @theme directive. For a nonstandard entry location, declare the file explicitly:

{
  "teacss": {
    "entry": "./src/styles/tea.css"
  }
}

Connect Astro

The Astro integration registers the Vite plugin and injects the generated stylesheet into pages:

// astro.config.mjs
import { defineConfig } from "astro/config";
import { teacss } from "@teacss/astro";

export default defineConfig({
  integrations: [teacss()],
});

Do not import virtual:teacss.css again with Astro’s default injection. To own the import instead, pass teacss({ injectEntry: false }) and import the virtual stylesheet once. injectExtra appends module statements without replacing the default stylesheet import.

When using Astra and Aster

Their components rely on the application’s TeaCSS build. Import Astra’s shortcut declarations and scan both packages, including their CSS and Astro files, from the project-root entry:

@import "@yiplex/astra/index.shortcuts.css";
@presets "standard,icons,official";
@source "./src/**/*.{astro,html,js,jsx,ts,tsx,md,mdx,css}";
@source "./node_modules/@yiplex/astra/dist/**/*.{js,astro,css}";
@source "./node_modules/@yiplex/aster/dist/**/*.{js,astro,css}";
@teacss;

Keep both packages in Astro’s SSR build with vite: { resolve: { noExternal: ["@yiplex/astra", "@yiplex/aster"] } }. An application using only Astra can omit the Aster path and SSR entry. Yiplex 0.1.10 has its own Node.js and Astro requirements; see Astra and Aster.

Connect Vite

For a non-Astro Vite application, register the plugin and import its virtual stylesheet once from the application entry:

// vite.config.ts
import { defineConfig } from "vite";
import { teacss } from "@teacss/vite";

export default defineConfig({
  plugins: [teacss()],
});

// src/main.ts
import "virtual:teacss.css";

The adapter scans the module graph, updates CSS during development, and emits a CSS asset for production.

Generate a standalone stylesheet

When no bundler owns the module graph, the CLI reads the same CSS entry:

bunx teacss build --out tea.css --unmatched error
bunx teacss watch --out tea.css

The CLI reads source paths from the entry’s @source declarations. Use --entry <file> to select a different entry.

Confirm the output

Put a literal token in a scanned file, such as <div class="p:4 bg-color:neutral-100">Hello</div>, then build and inspect the corresponding padding and background rules. An unknown or near-known value fails under teacss build --unmatched error; unrelated class names are ignored. After a site build, run teacss audit dist to find classes that reached the HTML without a corresponding CSS rule.

If a class has no rule, inspect the source glob, enabled preset, token spelling, and entry import. TeaCSS cannot discover "p:" + size; keep complete tokens static or declare their exact possibilities with @safelist.

Continue with Syntax and Standard.