# How to Build Astryx for a Specific Platform: Pre-Built vs. Source Build Guide

> Learn how to build Astryx for your specific platform. Use pre-built packages for quick deployment or the build toolkit for custom JavaScript platforms with CSS isolation.

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

---

**Build Astryx for a specific platform using either pre-built npm packages for instant web deployment or the `@astryxdesign/build` toolkit for custom JavaScript platforms requiring CSS layer isolation.**

Astryx is Meta's design system built on StyleX. Depending on your target platform, you can consume it as ready-to-run CSS bundles or compile from source with full pipeline control. This guide covers both approaches based on the facebook/astryx repository structure.

## Pre-Built Web Distribution: Zero Compilation

The fastest way to build Astryx for a specific platform is to skip compilation entirely. Astryx ships fully compiled CSS bundles in `packages/core/dist/css/` that work in any modern browser.

### Installation

```bash
pnpm add @astryxdesign/core @astryxdesign/theme-neutral

```

### CSS Import Order

Import styles in this exact sequence to ensure proper cascade:

```tsx
import '@astryxdesign/core/dist/css/core.css';
import '@astryxdesign/theme-neutral/dist/css/theme.css';
import './src/App.css';

```

### Theme Provider Setup

Wrap your React tree when using Astryx themes:

```tsx
import {ThemeProvider} from '@astryxdesign/theme-neutral';

function App() {
  return (
    <ThemeProvider>
      {/* your application */}
    </ThemeProvider>
  );
}

```

**Key benefit:** No Babel, PostCSS, or Vite plugins required. The browser receives ready-to-use class names directly from [`packages/core/dist/css/core.css`](https://github.com/facebook/astryx/blob/main/packages/core/dist/css/core.css).

## Source Build for Custom JavaScript Platforms

When you need to compile StyleX source—whether to isolate Astryx's CSS in separate layers, mix with Tailwind, or target specific browser capabilities—use the build plugins in `@astryxdesign/build`.

### Step 1: Install Build Dependencies

```bash
pnpm add -D @astryxdesign/build @stylexjs/babel-plugin @babel/core

```

### Step 2: Configure Babel

Route Astryx files through the `astryx` class-name prefix while your code uses the default `x` prefix. In `babel.config.cjs`:

```js
module.exports = {
  presets: ['@babel/preset-env', '@babel/preset-react', '@babel/preset-typescript'],
  plugins: [
    [
      '@astryxdesign/build/babel',
      {
        astryxPackageScopes: ['@astryxdesign'],
      },
    ],
  ],
};

```

### Step 3: Add PostCSS Plugin (Optional)

For projects using PostCSS, configure layer separation in `postcss.config.cjs`:

```js
module.exports = {
  plugins: [
    require('@astryxdesign/build/postcss')({
      astryxLayer: 'astryx',
      appLayer: 'app',
    }),
  ],
};

```

### Step 4: Build Packages

Compile core and theme packages before consumption:

```bash
pnpm -F @astryxdesign/core build
pnpm -F @astryxdesign/theme-neutral build

```

### Step 5: Consume Built Artifacts

Import the compiled CSS as with the pre-built distribution. Now styles live in separate `@layer` blocks, preventing specificity collisions with your own CSS.

## Platform-Specific Build Considerations

| Platform | Build Approach | Special Requirements |
|----------|--------------|----------------------|
| **Standard web browsers** | Pre-built distribution | None—import CSS directly |
| **Next.js** | Either pre-built or source | For source: add `@astryxdesign/build` plugins, then `next build` |
| **Vite** | Source build recommended | Use Vite plugin from `@astryxdesign/build` (see `apps/example-vite/`) |
| **Storybook** | Source build | Build Astryx first (`pnpm build`), then `pnpm -F @astryxdesign/storybook build` |
| **Legacy browsers** | Source build with fallbacks | Run `astryx docs browser-support` to check CSS feature support |
| **React Native / Expo** | Not supported | Astryx is web-only; build separate native component library |

## Why Use Source Build for Specific Platforms?

**Layered CSS isolation** — The PostCSS plugin splits generated CSS into distinct `@layer` blocks, eliminating specificity clashes when combining with Tailwind or other CSS-in-JS solutions.

**Custom theming** — Author themes in TypeScript/StyleX and compile alongside Astryx, baking design-token overrides directly into final CSS.

**Browser compatibility control** — For platforms lacking modern CSS like `light-dark()` or `@container`, the `astryx docs browser-support` command (documented in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md)) lists required features and polyfill strategies.

## Quick-Start Cheat Sheet

```bash

# Pre-built path (fastest)

pnpm add @astryxdesign/core @astryxdesign/theme-neutral

# → Import CSS files, no build step

# Source build path (maximum control)

pnpm add -D @astryxdesign/build @stylexjs/babel-plugin @babel/core

# → Configure Babel/PostCSS, build packages, consume layered CSS

```

## Summary

- **Pre-built distribution** — Install npm packages, import CSS, deploy. No compilation needed. Fastest path for standard browsers.
- **Source build** — Use `@astryxdesign/build` plugins for platforms requiring CSS layer isolation, custom theming, or legacy browser support.
- **Babel configuration** — Route Astryx packages through dedicated class-name prefixes to separate design system styles from application code.
- **Platform-specific tooling** — Reference example apps in `apps/example-nextjs-source/`, `apps/example-vite/`, and `apps/storybook/` for complete working configurations.

## Frequently Asked Questions

### Does Astryx require a build step for all platforms?

No. The pre-built distribution in `packages/core/dist/css/` works without any compilation. Install `@astryxdesign/core` and `@astryxdesign/theme-neutral`, import the CSS files, and use the `ThemeProvider` component. Build plugins are only necessary when you need CSS layer isolation or custom compilation behavior.

### How do I build Astryx for Next.js specifically?

Next.js supports both approaches. For the pre-built path, import CSS directly in [`layout.tsx`](https://github.com/facebook/astryx/blob/main/layout.tsx) or [`_app.tsx`](https://github.com/facebook/astryx/blob/main/_app.tsx). For source builds, add `@astryxdesign/build` Babel configuration, build the packages with `pnpm -F @astryxdesign/core build`, then run `next build`. The `apps/example-nextjs-source/` directory contains a complete reference implementation.

### Can I build Astryx for React Native or mobile platforms?

No. According to the facebook/astryx source code, Astryx is a web-only design system with no native implementation. For React Native or Expo applications, you must build a separate component library. The CLI command `astryx docs browser-support` helps verify CSS feature requirements for mobile WebViews when using the web build.

### What files should I reference for build configuration examples?

Key documentation files in the repository include: [`packages/core/README.md`](https://github.com/facebook/astryx/blob/main/packages/core/README.md) for pre-built usage, [`packages/build/README.md`](https://github.com/facebook/astryx/blob/main/packages/build/README.md) for plugin configuration, [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md) for browser support commands, and [`apps/example-nextjs-source/README.md`](https://github.com/facebook/astryx/blob/main/apps/example-nextjs-source/README.md) for a complete source-build workflow.