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

> Learn how to install Astryx in React 19. Follow our guide to add the core package and theme, import CSS, and wrap your app with the Theme provider for a seamless setup.

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

---

**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](https://github.com/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)](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml) and [[`package.json`](https://github.com/facebook/astryx/blob/main/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/`](https://github.com/facebook/astryx/blob/main/packages/core/README.md) |
| `@astryxdesign/cli` | CLI tooling for components, templates, codemods | [`packages/cli/`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md) |
| `@astryxdesign/theme-*` | Pre-built themes (neutral, butter, etc.) | [`packages/themes/`](https://github.com/facebook/astryx/tree/main/packages/themes) |
| `@astryxdesign/build` | Build plugins for StyleX source builds | [`packages/build/`](https://github.com/facebook/astryx/tree/main/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/`](https://github.com/facebook/astryx/tree/main/packages/themes):

```bash

# 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)](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:

```css
/* 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:

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

```tsx
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)](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)](https://github.com/facebook/astryx/blob/main/packages/cli/README.md):

```bash

# 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`](https://github.com/facebook/astryx/blob/main/README.md) | High-level overview and quick-start | [Repository root](https://github.com/facebook/astryx/blob/main/README.md) |
| [`packages/core/README.md`](https://github.com/facebook/astryx/blob/main/packages/core/README.md) | Core package installation and framework guides | [`packages/core/`](https://github.com/facebook/astryx/blob/main/packages/core/README.md) |
| [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md) | CLI command reference and JSON API | [`packages/cli/`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md) |
| [`pnpm-workspace.yaml`](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml) | Monorepo workspace package definitions | [Root config](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml) |
| [`docs/release.md`](https://github.com/facebook/astryx/blob/main/docs/release.md) | Version compatibility and release notes | [`docs/`](https://github.com/facebook/astryx/blob/main/docs/release.md) |

## 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)](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`](https://github.com/facebook/astryx/blob/main/reset.css), [`astryx.css`](https://github.com/facebook/astryx/blob/main/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/blob/main/packages/themes/README.md)](https://github.com/facebook/astryx/tree/main/packages/themes).