How to Use the Astryx Build Package for Custom Builds

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.

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

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

npx astryx build --config astryx.build.js

Programmatic usage:

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

# 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 containing only the Button component styles and core theme variables.

Themed UMD Bundle Example

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

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