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

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 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:

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

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

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:

npx astryx theme build butter --watch

Editing src/butterTheme.ts triggers automatic CSS regeneration via the file watcher.

Production Integration Examples

One-Off Compilation (Default Output)

npx astryx theme build matcha

# Creates dist/matcha.css

Custom Output Path with Minification

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:

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:

# .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: 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 or 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 for the base design system. The CLI loads these files and applies any custom overrides defined via defineTheme before generating the final CSS.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}