# How to Use the Astryx Build Package for Custom Builds

> Learn to use the Astryx build package for custom builds. Compile StyleX source files into optimized CSS bundles with the CLI or programmatic API.

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

---

**The `@astryxdesign/build` package provides a CLI and programmatic API to compile StyleX source files into optimized CSS bundles containing only the components and themes you specify.**

The Astryx design system from the `facebook/astryx` repository ships with a dedicated build package for projects requiring fine-grained control over their CSS output. While the CDN version offers pre-built styles, the `@astryxdesign/build` package lets you selectively compile components from `packages/core/src` and bake custom theme overrides directly into the final bundle. This approach minimizes payload size by excluding unused components while preserving full access to Astryx's **StyleX**-based architecture.

## Installation and Setup

Install the build package as a dev dependency in your project or monorepo. The package exposes both a command-line interface and a JavaScript API for integration into existing build pipelines.

```bash
npm install -D @astryxdesign/build

# or

pnpm add -D @astryxdesign/build

```

The CLI entry point is available at `node_modules/.bin/astryx` when paired with the `@astryxdesign/cli` package, or you can invoke the build module directly at `packages/build/build.mjs` for programmatic usage.

## Configuration File Structure

Create an [`astryx.build.js`](https://github.com/facebook/astryx/blob/main/astryx.build.js) (or JSON) configuration file to define entry points and theme customizations. This file specifies which components to compile and how to override the default design tokens.

```javascript
// astryx.build.js
export default {
  entry: [
    'packages/core/src/components/Button',
    'packages/core/src/components/Card',
  ],
  theme: {
    '--color-primary': '#0066ff',
    '--spacing-medium': '1rem',
  },
  outDir: 'dist/css',
};

```

The build system respects the `defineVars` and `createTheme` APIs from the core StyleX definitions, ensuring your custom properties are resolved at compile time rather than runtime.

## Running Custom Builds

Execute the build using the CLI wrapper defined in `packages/cli/src/commands/build.mjs` or import the build function directly from the package.

**Using the CLI:**

```bash
npx astryx build --config astryx.build.js

```

**Programmatic usage:**

```javascript
import { build } from '@astryxdesign/build';

await build({
  configPath: './astryx.build.js'
});

```

The core implementation in `packages/build/build.mjs` orchestrates the StyleX compiler, handles CSS minification, and writes the output to your specified directory. By default, the process generates a single [`astryx.css`](https://github.com/facebook/astryx/blob/main/astryx.css) file containing only the styles for your declared entry points.

## Advanced Build Options

The build package supports several flags and configuration properties for specialized output formats:

- **`--format`** – Specify output format as `css` (default) or `umd` for a JavaScript module that injects styles at runtime
- **`--minify`** – Compress final CSS using `csso` for production deployments
- **`--watch`** – Monitor source files for changes and recompile automatically during development
- **`--split`** – Emit separate CSS files per component entry point to enable lazy-loading strategies
- **`--theme`** – Path to a JSON file containing CSS custom-property overrides

### Minimal Custom Build Example

```bash

# astryx.build.js

export default {
  entry: ['packages/core/src/components/Button'],
  outDir: 'public/css',
};

npx astryx build --config astryx.build.js

```

This produces [`public/css/astryx.css`](https://github.com/facebook/astryx/blob/main/public/css/astryx.css) containing only the Button component styles and core theme variables.

### Themed UMD Bundle Example

```javascript
// build.js
import { build } from '@astryxdesign/build';

await build({
  entry: [
    'packages/core/src/components/Modal',
    'packages/core/src/components/Tooltip',
  ],
  theme: './my-theme.json',
  outDir: './dist',
  format: 'umd',
  minify: true,
});

```

The resulting [`dist/astryx.umd.js`](https://github.com/facebook/astryx/blob/main/dist/astryx.umd.js) file injects the compiled CSS with your custom theme values when executed in the browser. Reference the `scripts/build-umd.mjs` file in the repository for additional UMD configuration patterns.

## Summary

- **`@astryxdesign/build`** packages the StyleX compiler and CSS minification tools from the `facebook/astryx` repository for custom build workflows.
- Configuration is handled via [`astryx.build.js`](https://github.com/facebook/astryx/blob/main/astryx.build.js), supporting entry point arrays, theme token overrides, and output directory specifications.
- The CLI (`npx astryx build`) and programmatic API (`build()`) both resolve through `packages/build/build.mjs`.
- Advanced options include UMD format generation, code splitting per component, watch mode, and external theme file imports.
- Generated CSS contains only the components you specify, optimizing bundle size while maintaining design system consistency.

## Frequently Asked Questions

### How do I install the Astryx build package in an existing project?

Install `@astryxdesign/build` as a dev dependency using your preferred package manager. The package requires Node.js and works alongside the core Astryx design system files to compile StyleX definitions into static CSS.

### Can I use the build package without the Astryx CLI?

Yes. While the CLI wrapper in `packages/cli/src/commands/build.mjs` provides convenient command-line access, you can import the `build` function directly from `@astryxdesign/build` and invoke it programmatically with a configuration object or path.

### What is the difference between CSS and UMD output formats?

The default `css` format writes a static stylesheet file that you link in your HTML or import into your bundler. The `umd` format generates a JavaScript module that injects the styles into the document at runtime, useful for CDN distribution or environments where you cannot add link tags directly.

### How do I apply custom themes during the build process?

Pass a `theme` property in your [`astryx.build.js`](https://github.com/facebook/astryx/blob/main/astryx.build.js) configuration or use the `--theme` CLI flag pointing to a JSON file. The build process resolves these values against the `defineVars` and `createTheme` APIs in the source files, baking the final CSS custom property values into the generated stylesheet.