# How to Set Up the Build Package for StyleX Astryx Source Builds

> Set up the @astryxdesign/build package for StyleX Astryx source builds. Get zero-config Vite pipeline to compile Astryx components into production-ready modules and CSS.

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

---

**The `@astryxdesign/build` package provides a zero-configuration Vite-based build pipeline that compiles Astryx components using the StyleX CSS-in-JS engine into production-ready ES modules, CommonJS bundles, and extracted CSS files.**

Setting up the build infrastructure for the Astryx design system requires configuring the dedicated build package that handles StyleX compilation. The `facebook/astryx` repository isolates this functionality in `packages/build`, publishing it as `@astryxdesign/build` to enable standalone compilation of component libraries without dragging in documentation or example application dependencies.

## Install the Build Package

The build system is distributed as a separate package to keep production dependencies lean. You can use it within the monorepo or install it in external projects.

### Clone and Bootstrap the Monorepo

If you are working with the source directly, start by cloning the repository and installing workspace dependencies:

```bash
git clone https://github.com/facebook/astryx.git
cd astryx
pnpm install

```

This installs all workspace packages, including `@astryxdesign/build` and its peers like `vite` and `@astryxdesign/stylex`.

### Add to an External Project

For consuming repositories, add the package as a development dependency:

```bash
pnpm add -D @astryxdesign/build

```

## Configure the Build Pipeline

While the package works without configuration, you can customize output paths and source maps by creating an `astryx.config.mjs` file at your project root:

```javascript
// astryx.config.mjs
export default {
  outputDir: 'dist',
  sourcemap: true,
};

```

The build package automatically detects this file and merges it with the default Vite configuration defined in [`packages/build/vite.config.ts`](https://github.com/facebook/astryx/blob/main/packages/build/vite.config.ts).

## Execute Builds

The package exposes a CLI through the `astryx` binary. All build operations trigger the Vite pipeline configured in `packages/build/src/cli.mjs`.

### Production Build

Generate optimized ES modules, CommonJS bundles, and minified CSS:

```bash
pnpm exec astryx build

```

By default, this writes artifacts to `./dist`, including [`index.esm.js`](https://github.com/facebook/astryx/blob/main/index.esm.js), [`index.cjs.js`](https://github.com/facebook/astryx/blob/main/index.cjs.js), and [`stylex.css`](https://github.com/facebook/astryx/blob/main/stylex.css).

### Development Watch Mode

Enable hot-module replacement for iterative development:

```bash
pnpm exec astryx build --watch

```

This launches the Vite dev server with file watching configured in `packages/build/src/cli.mjs`, automatically recompiling components when source files change.

## Build Architecture

Understanding the internal architecture helps debug issues and customize behavior. The pipeline consists of four layers orchestrated through `packages/build`.

### CLI Layer (`cli.mjs`)

The entry point at `packages/build/src/cli.mjs` parses command-line flags (`--watch`, `--prod`, `--output`) and initializes the Vite build process. It handles environment validation and merges user configuration with internal defaults before invoking the compiler.

### Vite Configuration ([`vite.config.ts`](https://github.com/facebook/astryx/blob/main/vite.config.ts))

The [`packages/build/vite.config.ts`](https://github.com/facebook/astryx/blob/main/packages/build/vite.config.ts) file configures the build orchestration. It registers the StyleX plugin, sets up CSS extraction, and defines output formats for both ESM and CommonJS. This configuration handles `.tsx` and `.ts` files through the TypeScript compiler.

### StyleX Plugin (`stylex-plugin.mjs`)

The core transformation logic lives in `packages/build/src/stylex-plugin.mjs`. This Vite plugin hooks into the build lifecycle, running the StyleX compiler on every component file to generate deterministic atomic class names and extract styles into a single CSS bundle.

### TypeScript Compilation ([`tsconfig.build.json`](https://github.com/facebook/astryx/blob/main/tsconfig.build.json))

Type checking and declaration file generation use [`packages/build/tsconfig.build.json`](https://github.com/facebook/astryx/blob/main/packages/build/tsconfig.build.json). During the build, this configuration emits [`.d.ts`](https://github.com/facebook/astryx/blob/main/.d.ts) files alongside JavaScript bundles, ensuring consuming projects have full type safety.

## Consume Build Outputs

After compilation, import the generated ES module bundle directly:

```tsx
import { Button } from './dist/index.esm.js';
import '@astryxdesign/build/dist/stylex.css';

```

The CSS file contains all StyleX-generated atomic styles. You must import or link this stylesheet in your application, as the build output contains only generated class names, not the StyleX runtime.

## Integrate with External Bundlers

The `@astryxdesign/build` output is standard JavaScript and integrates with any bundler.

### Next.js Configuration

Point webpack to the compiled distribution:

```javascript
// next.config.js
const path = require('path');

module.exports = {
  webpack(config) {
    config.resolve.alias['@astryx/design'] = path.resolve(__dirname, 'dist');
    return config;
  },
};

```

### Webpack Alias Setup

For custom webpack configurations, add a resolve alias pointing to the `dist` folder to use the pre-compiled Astryx components instead of the source.

## Troubleshoot Common Issues

### Missing StyleX Runtime

Ensure the consuming project has `@astryxdesign/stylex` installed. The build output contains generated CSS class names but requires the runtime library to resolve styles at execution time.

### CSS Not Loading

Verify your application imports the generated stylesheet. The build produces [`dist/stylex.css`](https://github.com/facebook/astryx/blob/main/dist/stylex.css) which must be included via import or link tag:

```javascript
import '@astryxdesign/build/dist/stylex.css';

```

### TypeScript Declarations Not Found

The build emits [`.d.ts`](https://github.com/facebook/astryx/blob/main/.d.ts) files using [`tsconfig.build.json`](https://github.com/facebook/astryx/blob/main/tsconfig.build.json). Ensure your consuming project's [`tsconfig.json`](https://github.com/facebook/astryx/blob/main/tsconfig.json) includes the `dist/**/*.d.ts` pattern in its `include` array.

### Watch Mode Stalls

For large codebases, Vite's file watching can throttle. Increase the watch interval by passing `--watchThrottle=200` to the CLI, or split your library into multiple entry points to reduce the file scan scope.

## Summary

- The `@astryxdesign/build` package isolates compilation logic from the core Astryx library in the `facebook/astryx` monorepo.
- The build pipeline relies on Vite configured through [`packages/build/vite.config.ts`](https://github.com/facebook/astryx/blob/main/packages/build/vite.config.ts) and custom StyleX transformation via `packages/build/src/stylex-plugin.mjs`.
- Running `astryx build` produces three artifacts: an ES module bundle, a CommonJS bundle, and a [`stylex.css`](https://github.com/facebook/astryx/blob/main/stylex.css) file containing extracted atomic styles.
- You must manually import the generated CSS file in consuming applications, as the build does not automatically inject styles.
- TypeScript declarations are generated alongside JavaScript using [`packages/build/tsconfig.build.json`](https://github.com/facebook/astryx/blob/main/packages/build/tsconfig.build.json).

## Frequently Asked Questions

### What is the difference between `@astryxdesign/build` and `packages/core`?

`@astryxdesign/build` is a standalone compiler package that processes Astryx components into distributable JavaScript and CSS. `packages/core` contains the actual React component source code. The build package is deliberately isolated so you can compile components without installing Storybook, documentation tools, or example application dependencies from the main repository.

### Why are my styles not appearing after running the build?

The `@astryxdesign/build` package extracts StyleX-generated atomic CSS into a separate file, typically [`dist/stylex.css`](https://github.com/facebook/astryx/blob/main/dist/stylex.css), but does not automatically inject it into your HTML. You must import this CSS file in your application entry point or include it in your HTML template. The JavaScript bundle contains only class name references, not the actual style rules.

### Can I customize the Vite configuration beyond the CLI flags?

Yes. Create a custom Vite configuration file that imports the StyleX plugin from `@astryxdesign/build/src/stylex-plugin.mjs` and merges it with your additional plugins. You can then pass this configuration to the `astryx` CLI using the `--config` flag, or use the Vite API directly to programmatically trigger builds with extended rollup options or additional preprocessing steps.

### Where are the TypeScript declaration files generated?

The build process emits [`.d.ts`](https://github.com/facebook/astryx/blob/main/.d.ts) declaration files alongside the JavaScript bundles in your configured `outputDir` (default `dist/`). These are generated using the [`packages/build/tsconfig.build.json`](https://github.com/facebook/astryx/blob/main/packages/build/tsconfig.build.json) configuration. If your IDE cannot find types, verify that your consuming project's [`tsconfig.json`](https://github.com/facebook/astryx/blob/main/tsconfig.json) includes the path to these declaration files, or ensure the `types` field in your [`package.json`](https://github.com/facebook/astryx/blob/main/package.json) points to the generated entry declaration file.