Plugin Config

CSSzyx is configured by passing options directly to the plugin. There is no standalone csszyx.config.ts file — all config lives in your bundler config.

Quick Start

import csszyx from 'csszyx/vite';
import tailwindcss from '@tailwindcss/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    ...csszyx({
      development: {
        debug: true,
      },
      production: {
        mangle: true,
        injectChecksum: true,
      },
      build: {
        astBudgetLimit: 50_000, // optional, default 50k
        cache: true,            // optional, enabled by default
      },
    }),
    tailwindcss(),
    react(),
  ],
});

import type { NextConfig } from 'next';
const csszyxWebpack = require('@csszyx/unplugin/webpack').default;

const nextConfig: NextConfig = {
  webpack(config) {
    config.plugins.push(
      csszyxWebpack({
        production: { mangle: true, injectChecksum: true },
      }),
    );
    return config;
  },
};

export default nextConfig;

const csszyxWebpack = require('@csszyx/unplugin/webpack').default;

module.exports = {
  plugins: [
    csszyxWebpack({
      production: { mangle: true, injectChecksum: true },
    }),
  ],
};

TypeScript Types

import type { PartialCsszyxConfig } from "@csszyx/types";

const csszyxOptions: PartialCsszyxConfig = {
  exclude: ["src/generated/**"],
  development: { debug: true },
  production: { mangle: true },
};

Configuration Sections

`development`

Controls development mode behavior.

interface DevelopmentConfig {
  strictMode: boolean; // Treat warnings as errors
  debug: boolean; // Enable debug logging
}

Option	Default	Description
`strictMode`	`false`	Treat all CSSzyx warnings as build errors
`debug`	`false`	Enable verbose debug logging

For per-element hydration recovery, use the szRecover JSX attribute on individual elements rather than a global flag — see SSR & Hydration → Recovery Tokens.

`production`

Controls production build behavior.

interface ProductionConfig {
  mangle: boolean; // Minify class names (z, y, x, ...)
  mangleVars: boolean; // Opt into dynamic sz CSS variable mangling and hoisting
  mangleVarHoistMaxDepth: number; // Max cascade depth for mangleVars hoisting
  mangleGlobalVars?: GlobalVarMangleConfig; // Explicit global token alias tier
  contentHashing: boolean; // Hash for immutable caching
  injectChecksum: boolean; // Add hydration checksum to HTML
  incrementalBuild: boolean; // Enable build caching
  minify: boolean; // Minify output
}

interface GlobalVarMangleConfig {
  enabled: boolean;
  mode?: 'alias';
  tokens?: string[];
  autoPrefix?: string;
  onUnsafeUsage?: 'error';
  reserved?: string[];
  emitMap?: boolean;
}

Option	Default	Description
`mangle`	`true`	Replace class names with short encoded symbols
`mangleVars`	`false`	Opt into shorter names and bounded hoisting for dynamic CSS variables generated from runtime `sz` values. Disabled builds keep existing `--_sz-*` output.
`mangleVarHoistMaxDepth`	`5`	Maximum DOM ancestor distance for component-tier CSS variable hoisting when `mangleVars` is enabled.
`mangleGlobalVars`	`undefined`	Opt-in alias gate for explicit app-owned global CSS custom properties. Phase H v1 is alias-only and keeps original public variables defined.
`contentHashing`	`true`	Hash CSS output for cache-busting
`injectChecksum`	`true`	Embed SHA-256 checksum in HTML
`incrementalBuild`	`true`	Cache build artifacts for faster rebuilds
`minify`	`true`	Minify emitted CSS and JS

mangleVars does not define global theme-token aliases. It only rewrites the dynamic CSS variables csszyx emits for runtime sz values, such as p: pad, and keeps the feature opt-in while the global token tier remains a separate design surface.

mangleGlobalVars enables the Phase H global token tier for explicit tokens. It is default-off, accepts only mode: 'alias', and must not remove original CSS custom-property names. autoPrefix remains disabled until csszyx can build the same alias table before source transforms and CSS output validation. Set emitMap: false only when the standalone .csszyx/global-var-map.json tooling asset is not needed; csszyx-manifest.json still includes globalVarAliases when aliases exist.

`build`

Controls the build pipeline.

interface BuildConfig {
  buildId?: string; // Build identifier (auto-generated if omitted)
  tailwindConfig?: string; // Path to Tailwind config file
  outputDir?: string; // Output directory
  cacheDir?: string; // Cache directory
  cache?: boolean; // Enable per-file transform cache
  astBudgetLimit?: number; // Max AST nodes per file before throwing
  parser?: "babel" | "oxc" | "rust"; // Source parser for JSX/TSX sz transforms
  scanCss?: string | string[]; // CSS files with @theme blocks to auto-scan
}

Option	Default	Description
`buildId`	Auto	Unique build identifier
`tailwindConfig`	`'tailwind.config.js'`	Tailwind configuration path
`outputDir`	`'.csszyx'`	Plugin output directory
`cacheDir`	`'.csszyx/cache'`	Incremental build cache
`cache`	`true`	Enable the per-file transform cache. Set to `false` when debugging parser output or isolating cache-related issues.
`astBudgetLimit`	`50000`	Throws `ASTBudgetExceededError` past this — guards against pathologically large generated files. Raise (e.g. `100_000`) for repos with json-as-ts or schema fixtures, or exclude the file via top-level `exclude`.
`parser`	`'rust'`	Source parser for JSX/TSX sz transforms. Default uses the native Rust engine through the matching optional `@csszyx/core-*` platform package; csszyx fails loudly when the package is missing. Set `'oxc'` to opt into the previous JavaScript oxc-parser path on unsupported platforms or for parser-edge-case triage; `'babel'` is the final compatibility escape hatch.
`scanCss`	`undefined`	CSS files to scan for `@theme` blocks. Literal paths and simple globs are supported.

File Filters

Use top-level include / exclude to control which source files csszyx parses. Filters accept literal paths, simple globs, or RegExp patterns. Excludes run before AST parsing, so large generated files can be skipped without hitting the AST budget.

csszyx({
  exclude: ["src/generated/**", /icon-dump\.tsx$/],
});

Theme Auto-Scan (`scanCss`)

When set, the plugin parses @theme blocks in your CSS entry point and generates .csszyx/theme.d.ts — a declaration file that augments the CustomTheme interface in @csszyx/compiler. This surfaces custom design tokens (colors, spacing, fonts, radii, shadows) in sz prop IntelliSense without any manual type declarations.

...csszyx({
  build: {
    scanCss: 'src/index.css',  // path to CSS with @theme blocks
  },
})

@import "tailwindcss";

@theme {
  --color-brand-500: #6d28d9;
  --color-brand-600: #5b21b6;
  --spacing-prose: 65ch;
  --radius-card: 12px;
}

After the first build, .csszyx/theme.d.ts is generated. Add it to your tsconfig.json so TypeScript picks it up:

{ "include": ["src", ".csszyx/theme.d.ts"] }

Result: { bg: 'brand-500' } and { maxW: '--spacing-prose' } get full autocomplete and type-checking.

scanCss accepts a glob or array: ['src/index.css', 'src/tokens.css']. Theme files are watched in dev mode — hot-reload triggers type regeneration.

`hydration`

Controls SSR hydration verification.

interface HydrationConfig {
  strict: boolean; // Enable strict checks
  defaultRecoveryMode?: "csr" | "dev-only"; // Default recovery mode
  auditLog: boolean; // Log hydration events
}

Option	Default	Description
`strict`	`true`	Abort on any mismatch (non-configurable in production)
`defaultRecoveryMode`	`null`	No recovery by default
`auditLog`	`true`	Log all hydration events

`performance`

Controls performance optimizations.

interface PerformanceConfig {
  parallel: boolean; // Parallel processing during build
  workers?: number; // Worker thread count (auto-detected)
  optimizeVariables: boolean; // CSS variable optimization
  zeroRuntime: boolean; // Static optimization for zero-runtime cases
}

Option	Default	Description
`parallel`	`true`	Process files in parallel using worker threads
`workers`	Auto	Worker count (defaults to CPU cores)
`optimizeVariables`	`true`	Deduplicate CSS custom properties
`zeroRuntime`	`true`	Optimize static sz props to literal strings

Plugin Config

Quick Start

TypeScript Types

Configuration Sections

development

production

build