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

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

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

CSS Import Order

Import styles in this exact sequence to ensure proper cascade:

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:

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.

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

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:

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:

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

Step 4: Build Packages

Compile core and theme packages before consumption:

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) lists required features and polyfill strategies.

Quick-Start Cheat Sheet

# 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 or _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 for pre-built usage, packages/build/README.md for plugin configuration, packages/cli/README.md for browser support commands, and apps/example-nextjs-source/README.md for a complete source-build workflow.

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