# How to Compile Astryx Themes to Production CSS Using the Theme Build Command

> Compile Astryx themes to production CSS with the theme build command. Learn how to use npx astryx theme build <slug> for minified CSS bundles.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-07-02

---

**Use `npx astryx theme build <slug>` to compile StyleX token definitions into a minified CSS bundle ready for production deployment.**

The `facebook/astryx` repository provides a CLI tool that transforms design-system tokens into static stylesheets. When you need to compile Astryx themes to production CSS, the `astryx theme build` command executes a three-stage pipeline defined in `packages/cli/src/commands/build-theme.mjs` that processes StyleX definitions and outputs browser-ready assets.

## How the Theme Build Command Works

The theme build command orchestrates the transformation of TypeScript token modules into static CSS through three distinct operations. This process leverages the **XDSTheme** provider from `packages/cli/src/lib/theme.mjs` to ensure correct configuration application and honours any custom token overrides added via `defineTheme`.

### Loading the Theme Source

First, the CLI locates the theme entry point at `src/<slug>Theme.ts` (or [`src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/src/theme/tokens.stylex.ts) for the core theme). The loader resolves cross-package imports such as `@astryxdesign/core/theme/tokens.stylex` to gather all token definitions required for the build.

### Compiling with StyleX

Next, the command invokes the StyleX compiler via `scripts/build-css.mjs`. This script traverses the token definitions, substitutes runtime values with static equivalents, and generates the corresponding CSS rules. The compiler handles resolution logic to ensure tokens from dependency packages are correctly inlined.

### Writing the Production Bundle

Finally, the resulting CSS is written to your specified output path. By default, the command creates `dist/<slug>.css`. The output is minified and safe for production deployment, or you can enable source maps for debugging purposes.

## Running the Theme Build Command

Execute the command using npx to avoid global installation:

```bash
npx astryx theme build <slug> [--out <path>] [--watch] [--minify] [--sourcemap]

```

To build the "butter" theme to the default location:

```bash
npx astryx theme build butter

# Generates: ./dist/butter.css

```

### Command Line Options

The CLI supports several flags to control the build output:

- **`--out <path>`**: Specifies the destination file path. If omitted, the CLI defaults to `dist/<slug>.css`.
- **`--watch`**: Keeps the process alive and automatically recompiles when source files change, ideal for local development.
- **`--minify`**: Forces minification regardless of environment. The command minifies by default in production mode.
- **`--sourcemap`**: Generates a source map file alongside the CSS bundle.

### Development Watch Mode

Enable `--watch` during active development to see changes immediately:

```bash
npx astryx theme build butter --watch

```

Editing [`src/butterTheme.ts`](https://github.com/facebook/astryx/blob/main/src/butterTheme.ts) triggers automatic CSS regeneration via the file watcher.

## Production Integration Examples

### One-Off Compilation (Default Output)

```bash
npx astryx theme build matcha

# Creates dist/matcha.css

```

### Custom Output Path with Minification

```bash
npx astryx theme build stone --out static/css/stone.min.css --minify

```

### Using Compiled CSS in React Applications

Import the generated stylesheet into your application entry point and wrap your component tree with the theme provider:

```tsx
import './dist/butter.css';
import { XDSTheme, defaultTheme } from '@astryxdesign/core';

function App() {
  return (
    <XDSTheme theme={defaultTheme}>
      {/* Your UI components */}
    </XDSTheme>
  );
}

```

## CI/CD Pipeline Configuration

Automate theme compilation in your deployment workflow using the same CLI command as a build step:

```yaml

# .github/workflows/ci.yml

- name: Build Astryx theme
  run: npx astryx theme build butter --out ./public/css/butter.css

```

The generated CSS file can then be served as a static asset or inlined for critical-path rendering.

## Key Source Files Behind the Build

Understanding the underlying implementation helps debug complex builds or customize the compilation process:

- **`packages/cli/src/commands/build-theme.mjs`**: Implements the CLI command, parsing flags, loading the theme, and invoking the compiler.
- **`scripts/build-css.mjs`**: Core StyleX compilation logic that resolves cross-package token imports and generates static rules.
- **`packages/cli/src/lib/theme.mjs`**: Provides the **XDSTheme** instance used during compilation to apply theme configuration.
- **`packages/themes/<slug>/src/<slug>Theme.ts`**: Source file containing StyleX token definitions for specific themes (e.g., `butter`, `gothic`).
- **[`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts)**: Core token definitions shared across all themes in the design system.

## Summary

- The `astryx theme build` command compiles StyleX token modules into production-ready CSS using the pipeline in `packages/cli/src/commands/build-theme.mjs`.
- The process runs three stages: loading source files from `src/<slug>Theme.ts`, compiling via `scripts/build-css.mjs`, and writing to `dist/<slug>.css`.
- Use `--watch` for development hot-reloading and `--out` to customize the destination path.
- The command supports minification and source maps via `--minify` and `--sourcemap` flags.
- The **XDSTheme** provider ensures correct theme configuration during the build process.

## Frequently Asked Questions

### What file does the theme build command output by default?

By default, the command writes the compiled CSS to `dist/<slug>.css` in your project root. Use the `--out` flag to specify a custom file path such as [`public/css/theme.css`](https://github.com/facebook/astryx/blob/main/public/css/theme.css) or [`static/styles/bundle.css`](https://github.com/facebook/astryx/blob/main/static/styles/bundle.css).

### How does the build command resolve token imports from other packages?

The compiler in `scripts/build-css.mjs` traverses the dependency graph to resolve cross-package imports like `@astryxdesign/core/theme/tokens.stylex`. It inlines these token values into the final CSS bundle, ensuring all theme dependencies are consolidated into a single file.

### Can I use watch mode in a production environment?

No, the `--watch` flag is intended strictly for local development. It keeps the Node.js process alive to monitor file system changes. Production builds should execute the command once without the watch flag, typically as part of a CI pipeline step.

### Where are theme configurations defined before compilation?

Theme configurations reside in `packages/themes/<slug>/src/<slug>Theme.ts` for specific variants, or [`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts) for the base design system. The CLI loads these files and applies any custom overrides defined via `defineTheme` before generating the final CSS.