How to Install Astryx in a React 19 Project: Complete Setup Guide

Install Astryx by adding @astryxdesign/core and a theme package to your React 19+ project, then import the pre-built CSS and wrap your app in the Theme provider.

Astryx is Facebook's open-source design system built on React 19+ and StyleX. This article walks through how to install Astryx using the exact package structure and configuration patterns defined in the facebook/astryx repository.

What Gets Installed

Astryx follows a modular architecture with multiple published packages. According to the source analysis of [pnpm-workspace.yaml](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml) and [package.json](https://github.com/facebook/astryx/blob/main/package.json), the monorepo contains:

Package	Purpose	Source Path
@astryxdesign/core	UI components, theme system, utilities	packages/core/
@astryxdesign/cli	CLI tooling for components, templates, codemods	packages/cli/
@astryxdesign/theme-*	Pre-built themes (neutral, butter, etc.)	packages/themes/
@astryxdesign/build	Build plugins for StyleX source builds	packages/build/

The core and theme packages have peer dependencies on react and react-dom (both ≥ 19).

Step 1: Install Core Packages

Run one of the following commands based on your package manager. Replace theme-neutral with any available theme from packages/themes/:

# npm

npm install @astryxdesign/core @astryxdesign/theme-neutral
npm install -D @astryxdesign/cli

# pnpm

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

# yarn

yarn add @astryxdesign/core @astryxdesign/theme-neutral
yarn add -D @astryxdesign/cli

The CLI installs as a dev dependency because it provides build-time tooling only.

Step 2: Import Pre-Built CSS

Astryx ships pre-built CSS files—no PostCSS or Babel configuration required. As documented in [packages/core/README.md](https://github.com/facebook/astryx/blob/main/packages/core/README.md#quick-start), import the reset, base styles, and theme CSS in your global stylesheet:

/* src/app/globals.css (Next.js example) */
@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-neutral/theme.css';

This pattern works in any bundler: Next.js, Vite, or plain HTML projects.

Step 3: Configure the Theme Provider

Wrap your application in the Theme provider from @astryxdesign/core/theme. The LinkProvider integration enables proper routing component injection:

// src/app/providers.tsx
'use client';

import Link from 'next/link';
import {Theme} from '@astryxdesign/core/theme';
import {LinkProvider} from '@astryxdesign/core/Link';
import {neutralTheme} from '@astryxdesign/theme-neutral/built';

export function Providers({children}: {children: React.ReactNode}) {
  return (
    <Theme theme={neutralTheme}>
      <LinkProvider component={Link}>{children}</LinkProvider>
    </Theme>
  );
}

Import the built theme from /built subpaths for optimal tree-shaking performance.

Step 4: Use Components

Import components directly from their package paths. This enables tree-shaking and keeps bundle sizes minimal:

import {Button} from '@astryxdesign/core/Button';

export default function Demo() {
  return <Button label="Hello Astryx" variant="primary" />;
}

The core package exports 150+ accessible React components following the foundations defined in [packages/core/README.md](https://github.com/facebook/astryx/blob/main/packages/core/README.md): typography, color, layout, and accessibility systems.

Step 5: Run the CLI (Optional)

The @astryxdesign/cli package exposes commands for component discovery and project initialization. As implemented in [packages/cli/README.md](https://github.com/facebook/astryx/blob/main/packages/cli/README.md):

# Show all available commands

npx @astryxdesign/cli --help

# List every component in the library

npx @astryxdesign/cli component --list

# Initialize project with AGENTS.md/CLAUDE.md for AI assistants

npx @astryxdesign/cli init

The init command generates documentation files that expose the same API surface to AI coding assistants as to human developers.

Key Configuration Files

File	Purpose	Location
README.md	High-level overview and quick-start	Repository root
packages/core/README.md	Core package installation and framework guides	packages/core/
packages/cli/README.md	CLI command reference and JSON API	packages/cli/
pnpm-workspace.yaml	Monorepo workspace package definitions	Root config
docs/release.md	Version compatibility and release notes	docs/

Summary

• Install Astryx with npm install @astryxdesign/core @astryxdesign/theme-neutral plus the optional CLI dev dependency.
• Import CSS from pre-built files—no build plugin configuration needed.
• Wrap your app in the Theme provider with a built theme import for tree-shaking.
• Use components via direct path imports to maintain optimal bundle size.
• Leverage the CLI for component discovery and AI assistant documentation generation.

Frequently Asked Questions

Does Astryx require React 19 specifically?

Yes. According to the source analysis of [package.json](https://github.com/facebook/astryx/blob/main/package.json), both react and react-dom are listed as peer dependencies with version constraints >= 19.0.0. The design system relies on React 19 features and will not install correctly with earlier versions.

Can I use Astryx without the CLI?

Absolutely. The @astryxdesign/cli package is optional and provides developer-experience enhancements like component listing and codemods. Core functionality—components, themes, and styling—works without any CLI installation. The CLI installs as a dev dependency and never ships to production.

What build tools work with Astryx?

Any modern bundler. Because Astryx distributes pre-built CSS files (reset.css, astryx.css, theme CSS), it works in Next.js, Vite, Parcel, or plain HTML projects without additional configuration. The @astryxdesign/build package exists only for projects that need to compile StyleX source directly.

How do I switch to a different theme?

Install the desired theme package (e.g., @astryxdesign/theme-butter), update your CSS import to @astryxdesign/theme-butter/theme.css, and change the theme object in your provider to butterTheme from @astryxdesign/theme-butter/built. All themes follow the same structure documented in [packages/themes/README.md](https://github.com/facebook/astryx/tree/main/packages/themes).

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