# How to Install and Set Up Astryx in a React Project
> Install and set up Astryx in your React project. Learn to integrate the design system by installing core and theme packages, importing stylesheets, and wrapping your app with ThemeProvider.
- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: getting-started
- Published: 2026-07-15
---
**To install and set up Astryx in a React project, install the core package `@astryxdesign/core` and a theme package like `@astryxdesign/theme-neutral`, import the CSS reset and theme stylesheets in your entry file, then wrap your application with the `ThemeProvider` component to enable the design system.**
Astryx is a React-based open-source design system maintained by Meta (facebook/astryx) that provides a comprehensive component library with zero-config theming support. Learning how to install and set up Astryx requires only standard npm packages and works out-of-the-box with Vite, Next.js, and Create React App without custom build tooling.
## Prerequisites and Package Architecture
The Astryx ecosystem distributes functionality across three primary packages. The **core package** (`@astryxdesign/core`) contains the React component library and the `ThemeProvider` implementation located at [`packages/core/src/ThemeProvider.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/ThemeProvider.tsx). **Theme packages** (such as `@astryxdesign/theme-neutral`) supply CSS custom property defaults that control the visual appearance. The optional **CLI** (`@astryxdesign/cli`) provides development tooling for component discovery, documentation generation, and codemods.
## Installing Astryx Dependencies
Install the runtime dependencies using your preferred package manager. You must install both the core library and at least one theme package to render components correctly.
```bash
# Install runtime packages
npm install @astryxdesign/core @astryxdesign/theme-neutral
# Install the CLI as a dev dependency
npm install -D @astryxdesign/cli
```
TypeScript definitions are included in the packages, so no additional `@types` installations are required for TypeScript projects.
## Configuring the Theme Provider and Global Styles
After installation, import the CSS reset and theme stylesheet in your application entry point. The [`reset.css`](https://github.com/facebook/astryx/blob/main/reset.css) file normalizes browser defaults, while the theme CSS establishes the design token variables referenced by components.
Wrap your root component with the `ThemeProvider` exported from [`packages/core/src/ThemeProvider.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/ThemeProvider.tsx). This provider injects theme values into the React context tree, making design tokens available to all child components.
```tsx
// src/index.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { ThemeProvider } from '@astryxdesign/core';
import '@astryxdesign/core/dist/css/reset.css';
import '@astryxdesign/theme-neutral/dist/css/theme.css';
import App from './App';
ReactDOM.createRoot(document.getElementById('root')!).render(
,
);
```
## Using Astryx Components
Once the provider is configured, import components directly from the core package. All components consume the theme context automatically and require no additional styling imports per component.
```tsx
// src/App.tsx
import { Button, Card } from '@astryxdesign/core';
export default function App() {
return (
Hello Astryx!
);
}
```
## Setting Up the Astryx CLI for Development
Add a script entry to your [`package.json`](https://github.com/facebook/astryx/blob/main/package.json) to invoke the CLI without typing the full module path. The CLI binary is located at `node_modules/@astryxdesign/cli/bin/astryx.mjs`.
```json
{
"scripts": {
"astryx": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
}
}
```
Use the CLI to list available components, generate documentation, or run codemods for advanced customization workflows like "swizzling" component source into your project.
```bash
# List all available components
npm run astryx -- component --list
```
Detailed CLI capabilities are documented in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md).
## Framework Compatibility and Build Tools
Astryx requires no custom **Webpack**, **PostCSS**, or **Babel** configuration. The library works with standard React build tools including:
- **Vite** – Works with zero additional configuration
- **Next.js** – Compatible with both Pages and App Router
- **Create React App** – Requires no additional setup
- **CDN deployments** – Supported via unpkg or similar services
The official quick-start guide in [`packages/core/README.md`](https://github.com/facebook/astryx/blob/main/packages/core/README.md) provides specific integration examples for each environment.
## Summary
- **Install** the core package (`@astryxdesign/core`) and a theme package (e.g., `@astryxdesign/theme-neutral`) via npm.
- **Import** the CSS reset and theme CSS files in your entry point before rendering the application.
- **Wrap** your application with the `ThemeProvider` component from [`packages/core/src/ThemeProvider.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/ThemeProvider.tsx) to enable theming.
- **Add** the `@astryxdesign/cli` as a dev dependency and create an npm script referencing `node_modules/@astryxdesign/cli/bin/astryx.mjs` for easy access to component listing and codemods.
- **Use** components directly from the core package without additional build configuration.
## Frequently Asked Questions
### Does Astryx require custom Webpack or Babel configuration?
No. Astryx works out-of-the-box with standard React build tools like Vite, Next.js, and Create React App. The library ships with pre-built CSS and JavaScript that require no custom webpack, PostCSS, or Babel plugins according to the facebook/astryx source code.
### What theme packages are available for Astryx?
The standard theme package is `@astryxdesign/theme-neutral`, which provides the default CSS custom property values. Additional themes may be available in the `packages/themes/` directory. Check [`packages/themes/neutral/README.md`](https://github.com/facebook/astryx/blob/main/packages/themes/neutral/README.md) for theming documentation and customization options.
### How do I customize or override Astryx component styles?
You can customize styles by overriding the CSS custom properties defined in the theme package, or by using the CLI's "swizzle" feature to copy component source into your project for direct modification. The CLI workflow is documented in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md).
### Can I use Astryx with Next.js App Router?
Yes. Astryx is compatible with Next.js App Router. Import the CSS files in your root layout and wrap the application with `ThemeProvider` as you would in any React application. The library requires no server-specific configuration.