How Is the Astryx Repository Organized? Understanding the Directory Structure

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 – StyleX token definitions
• Theme.tsx – Theme provider component
• MediaTheme.tsx – Responsive theme handling
• 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:

pnpm -F apps/storybook dev

Storybook configuration lives at 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 – Ensures package entry points stay synchronized
• Template synchronization
• Stale branch pruning
• Export verification

Run repository maintenance tasks:

pnpm -F scripts run sync-exports

Configuration Files at Root

These files define how the monorepo operates:

File	Purpose
pnpm-workspace.yaml	Declares workspace globs (packages/*, apps/*)
tsconfig.json	Base TypeScript config inherited by all packages
vitest.config.ts	Test runner configuration for unit and snapshot tests
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

$ASTRYX component --list

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

Import a Core Component

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

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

Generate Theme Tokens

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

Key Entry Points

Path	Significance
packages/core/src/index.ts	Public API entry point for core package
packages/core/src/Button/Button.tsx	Exemplar component using StyleX
packages/core/src/theme/defineTheme.ts	Theming API for design tokens
.github/workflows/ci.yml	Complete CI pipeline definition
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. The 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.

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