How to Install and Set Up Astryx in a React Project

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. 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.

# 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 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. This provider injects theme values into the React context tree, making design tokens available to all child components.

// 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(
  <React.StrictMode>
    <ThemeProvider>
      <App />
    </ThemeProvider>
  </React.StrictMode>,
);

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.

// src/App.tsx
import { Button, Card } from '@astryxdesign/core';

export default function App() {
  return (
    <Card padding={4}>
      <h1>Hello Astryx!</h1>
      <Button variant="primary" onClick={() => alert('Clicked!')}>
        Click me
      </Button>
    </Card>
  );
}

Setting Up the Astryx CLI for Development

Add a script entry to your 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.

{
  "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.

# List all available components

npm run astryx -- component --list

Detailed CLI capabilities are documented in 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 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 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 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.

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.

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