# How Is the Astryx Repository Organized? Understanding the Directory Structure

> Explore the Astryx repository structure, a monorepo featuring a clear layout with packages, apps, and scripts directories. Understand its organization for efficient development.

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

---

**The Astryx repository is a monorepo that groups all design-system code, tooling, documentation, and CI configuration into a clear, layered layout centered around the `packages/`, `apps/`, and `scripts/` directories.**

This article breaks down the complete directory structure of Astryx—Facebook's open-source design system—to help you navigate the codebase efficiently. Whether you're contributing components, customizing themes, or integrating Astryx into your project, understanding where files live is essential.

## High-Level Directory Structure

Astryx uses **pnpm workspaces** to manage multiple publishable packages from a single root. Here's the complete tree:

```

├── .github/                     – GitHub Actions and workflow definitions
│   └── workflows/               – CI, release, and automation workflows
├── .changeset/                  – Changeset metadata for release automation
│   └── *.md                     – Release notes and versioning files
├── apps/                        – Example apps and internal tooling
│   ├── docsite/                 – Static documentation site
│   └── storybook/               – Live component explorer
├── docs/                        – Public documentation and release notes
│   └── *.md                     – User-facing guides
├── packages/                    – All publishable NPM packages
│   ├── core/                    – Main design-system package
│   ├── lab/                     – Experimental utilities
│   └── vega/                    – Visualization helpers
├── scripts/                     – Repository-wide automation scripts
├── .prettierrc.json             – Code formatting configuration
├── .npmignore                   – NPM publish exclusions
├── .gitignore                   – Git ignore patterns
├── package.json                 – Root workspace definition
├── pnpm-workspace.yaml          – pnpm workspace configuration
├── tsconfig.json                – Shared TypeScript configuration
├── vitest.config.ts             – Test runner configuration
└── README.md                    – Project overview

```

## The `packages/` Directory: Core Code

The `packages/` folder contains every module published to NPM. This is where the design system actually lives.

### `packages/core`: Heart of the Design System

`packages/core` is the primary package consumers install. Its internal structure reveals how Astryx separates concerns:

```

packages/core/
├── src/
│   ├── components/     – UI primitives (Button, IconButton, Checkbox, etc.)
│   ├── i18n/           – Internationalization helpers
│   ├── theme/          – Token-based theming and StyleX utilities
│   └── utils/          – Shared helpers (mergeProps, date parsing, RTL)
├── tsconfig.json       – Package-specific TypeScript settings
└── package.json        – Package manifest and dependencies

```

**Components** in `packages/core/src/components/` follow a consistent pattern. Each component folder contains:

- TypeScript implementation (`*.tsx`)
- Documentation module (`{Component}.doc.mjs`)
- Test files (`*.test.tsx`)

**The theme system** (`packages/core/src/theme/`) powers Astryx's sophisticated token-based styling:

- [`tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/tokens.stylex.ts) – StyleX token definitions
- [`Theme.tsx`](https://github.com/facebook/astryx/blob/main/Theme.tsx) – Theme provider component
- [`MediaTheme.tsx`](https://github.com/facebook/astryx/blob/main/MediaTheme.tsx) – Responsive theme handling
- [`defineTheme.ts`](https://github.com/facebook/astryx/blob/main/defineTheme.ts) – Core theming API for color, spacing, and typography tokens

**Internationalization** helpers in `packages/core/src/i18n/` include `useTranslator` and `useDirection` for locale-aware rendering.

### `packages/lab`: Experimental Utilities

`packages/lab` holds internal tools and experimental code not yet ready for public API surface. It maintains separate TypeScript configurations for documentation and production builds.

### `packages/vega`: Visualization Helpers

`packages/vega` provides charting and data visualization utilities used by internal Facebook tools.

## The `apps/` Directory: Examples and Tooling

The `apps/` folder contains runnable applications that demonstrate and document Astryx:

| App | Purpose | Key Location |
|-----|---------|--------------|
| **Storybook** | Live component explorer | `apps/storybook/` |
| **Docsite** | Static documentation site | `apps/docsite/` |

### Working with Storybook

Start the component development server:

```bash
pnpm -F apps/storybook dev

```

Storybook configuration lives at [`apps/storybook/.storybook/main.ts`](https://github.com/facebook/astryx/blob/main/apps/storybook/.storybook/main.ts), which imports and displays components from `packages/core`.

## The `scripts/` Directory: Automation

`scripts/` contains repository-wide automation used by CI and maintainers. Common operations include:

- [`sync-exports.js`](https://github.com/facebook/astryx/blob/main/sync-exports.js) – Ensures package entry points stay synchronized
- Template synchronization
- Stale branch pruning
- Export verification

Run repository maintenance tasks:

```bash
pnpm -F scripts run sync-exports

```

## Configuration Files at Root

These files define how the monorepo operates:

| File | Purpose |
|------|---------|
| [`pnpm-workspace.yaml`](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml) | Declares workspace globs (`packages/*`, `apps/*`) |
| [`tsconfig.json`](https://github.com/facebook/astryx/blob/main/tsconfig.json) | Base TypeScript config inherited by all packages |
| [`vitest.config.ts`](https://github.com/facebook/astryx/blob/main/vitest.config.ts) | Test runner configuration for unit and snapshot tests |
| [`package.json`](https://github.com/facebook/astryx/blob/main/package.json) | Root scripts and workspace metadata |

## CI and Release Configuration

### `.github/workflows/`

GitHub Actions handle continuous integration with workflows for:

- Linting and type-checking
- Running the full test suite
- Generating snapshot tests
- Deploying preview builds

### `.changeset/`

The **Changesets** tool manages versioning. Markdown files in `.changeset/` describe changes; these drive automated releases and changelog generation.

## Practical Navigation Examples

### List Available Components

```bash
$ASTRYX component --list

# Output: Button, IconButton, Checkbox, Switch, Card, Table, ...

```

### Import a Core Component

```tsx
// app/src/App.tsx
import {Button} from '@astryxdesign/core';

export default function App() {
  return <Button variant="primary">Click me</Button>;
}

```

### Run the Full Test Suite

```bash
pnpm test  # Vitest runs unit and snapshot tests across all packages

```

### Generate Theme Tokens

```bash
$ASTRYX theme --generate --output packages/core/src/theme/tokens.stylex.ts

```

## Key Entry Points

| Path | Significance |
|------|------------|
| [`packages/core/src/index.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/index.ts) | Public API entry point for core package |
| [`packages/core/src/Button/Button.tsx`](https://github.com/facebook/astryx/blob/main/packages/core/src/Button/Button.tsx) | Exemplar component using StyleX |
| [`packages/core/src/theme/defineTheme.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/defineTheme.ts) | Theming API for design tokens |
| [`.github/workflows/ci.yml`](https://github.com/facebook/astryx/blob/main/.github/workflows/ci.yml) | Complete CI pipeline definition |
| [`apps/storybook/.storybook/main.ts`](https://github.com/facebook/astryx/blob/main/apps/storybook/.storybook/main.ts) | Storybook configuration |

## Summary

- **Astryx uses a pnpm monorepo structure** with workspace packages in `packages/` and example apps in `apps/`
- **`packages/core`** contains all public UI components, theming via StyleX, i18n helpers, and shared utilities
- **`packages/lab`** and **`packages/vega`** provide experimental and visualization-specific code respectively
- **`apps/storybook`** and **`apps/docsite`** serve as the component showcase and documentation site
- **`scripts/`** houses automation that keeps the repository synchronized
- **`.github/workflows/`** and **`.changeset/`** manage CI and automated releases

## Frequently Asked Questions

### How do I add a new component to Astryx?

Create a new folder in `packages/core/src/components/` with your component name. Include the TypeScript implementation (`*.tsx`), documentation module (`*.doc.mjs`), and tests (`*.test.tsx`). Run `pnpm test` to verify, then submit a PR with a changeset file in `.changeset/`.

### What's the difference between `packages/core` and `packages/lab`?

`packages/core` contains stable, public-facing components published to NPM. `packages/lab` holds experimental utilities and internal tools that may change without notice—code here isn't part of the supported public API.

### How does the theming system work in Astryx?

Astryx uses a token-based approach powered by **StyleX**. Theme tokens are defined in [`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts). The [`defineTheme.ts`](https://github.com/facebook/astryx/blob/main/defineTheme.ts) API generates CSS variables for colors, spacing, and typography. Components consume these tokens through StyleX, enabling consistent, maintainable styling across light, dark, and custom themes.