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

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:

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:

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:

// 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.

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:

pnpm exec astryx build

By default, this writes artifacts to ./dist, including index.esm.js, index.cjs.js, and stylex.css.

Development Watch Mode

Enable hot-module replacement for iterative development:

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)

The 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)

Type checking and declaration file generation use packages/build/tsconfig.build.json. During the build, this configuration emits .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:

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:

// 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 which must be included via import or link tag:

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

TypeScript Declarations Not Found

The build emits .d.ts files using tsconfig.build.json. Ensure your consuming project's 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 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 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.

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, 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 declaration files alongside the JavaScript bundles in your configured outputDir (default dist/). These are generated using the packages/build/tsconfig.build.json configuration. If your IDE cannot find types, verify that your consuming project's tsconfig.json includes the path to these declaration files, or ensure the types field in your package.json points to the generated entry declaration file.

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