# Where Are the Astryx Source Files Located? A Complete Guide to the Repository Structure

> Discover where Astryx source files reside within the facebook/astryx repository. Learn about the organized monorepo structure and locate TypeScript/React code easily.

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

---

**Astryx source files are organized in a monorepo under the `packages/` directory, with TypeScript/React code living in `src/` subfolders within each functional package.**

The **Astryx design system** is maintained by Meta (formerly Facebook) as a multi-package repository. All source code is written in TypeScript and follows a consistent internal structure across packages. This guide walks through the exact file locations, package purposes, and how to navigate the codebase.

## Main Source Directory: `packages/`

All Astryx source code resides in the **`packages/`** folder at the repository root. This monorepo structure uses pnpm workspaces, defined in [`pnpm-workspace.yaml`](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml), to link independent packages together.

The workspace contains seven primary packages, each with its own `src/` directory:

| Package | Source Directory | Contents |
|:---|:---|:---|
| **core** | `packages/core/src/` | UI components (Button, Divider, Modal), utilities, styles, documentation |
| **charts** | `packages/charts/src/` | Chart primitives: [`Chart.tsx`](https://github.com/facebook/astryx/blob/main/Chart.tsx), [`ChartAxis.tsx`](https://github.com/facebook/astryx/blob/main/ChartAxis.tsx), [`ChartLegend.tsx`](https://github.com/facebook/astryx/blob/main/ChartLegend.tsx) |
| **vega** | `packages/vega/src/` | Vega-Lite integration: [`VegaChart.tsx`](https://github.com/facebook/astryx/blob/main/VegaChart.tsx) wrapper and typings |
| **richtext** | `packages/richtext/src/` | Rich-text editor entry point and utilities |
| **lab** | `packages/lab/` | Experimental playground and documentation demos |
| **cli** | `packages/cli/` | Command-line tools including `astryx.mjs` |

Each package is independently publishable with its own [`package.json`](https://github.com/facebook/astryx/blob/main/package.json), [`tsconfig.json`](https://github.com/facebook/astryx/blob/main/tsconfig.json), and build configuration.

## Core Package: The Heart of Astryx

The **`packages/core/src/`** directory contains the primary component library. Most consumers import from `@astryxdesign/core`, which resolves to this location.

Component folders follow a strict convention. Each component lives in its own directory with multiple files:

- [`index.ts`](https://github.com/facebook/astryx/blob/main/index.ts) — re-exports the public API
- [`ComponentName.tsx`](https://github.com/facebook/astryx/blob/main/ComponentName.tsx) — React/TypeScript implementation
- [`ComponentName.test.tsx`](https://github.com/facebook/astryx/blob/main/ComponentName.test.tsx) — unit tests
- `ComponentName.doc.mjs` — documentation metadata for the CLI

For example, the `Divider` component is fully contained in `packages/core/src/Divider/`:

```tsx
// packages/core/src/Divider/Divider.tsx
import { Divider } from '@astryxdesign/core';

export const Example = () => (
  <>
    <p>First section</p>
    <Divider />
    <p>Second section</p>
  </>
);

```

The `Divider.doc.mjs` file in the same folder provides structured documentation consumed by the Astryx CLI tooling.

## Chart and Visualization Sources

### Charts Package

The **`packages/charts/src/`** directory provides low-level charting primitives. The main entry point is [`Chart.tsx`](https://github.com/facebook/astryx/blob/main/Chart.tsx):

```tsx
import { Chart } from '@astryxdesign/charts';
import { chartData } from './data';

export const SalesChart = () => (
  <Chart
    data={chartData}
    xKey="date"
    yKey="revenue"
    type="line"
    height={300}
  />
);

```

Source file: [[`packages/charts/src/Chart/Chart.tsx`](https://github.com/facebook/astryx/blob/main/packages/charts/src/Chart/Chart.tsx)](https://github.com/facebook/astryx/blob/main/packages/charts/src/Chart/Chart.tsx)

### Vega Package

For **Vega-Lite** integration, source files are in `packages/vega/src/`:

```tsx
import { VegaChart } from '@astryxdesign/vega';

const spec = {
  mark: 'line',
  encoding: {
    x: { field: 'date', type: 'temporal' },
    y: { field: 'value', type: 'quantitative' }
  },
  data: { name: 'table' }
};

export const VegaExample = () => <VegaChart spec={spec} />;

```

Source file: [[`packages/vega/src/VegaChart.tsx`](https://github.com/facebook/astryx/blob/main/packages/vega/src/VegaChart.tsx)](https://github.com/facebook/astryx/blob/main/packages/vega/src/VegaChart.tsx)

## Shared Utilities and Configuration

### Utility Functions

Common utilities live alongside components. The **`packages/core/src/utils/`** directory contains helpers like [`mergeProps.ts`](https://github.com/facebook/astryx/blob/main/mergeProps.ts), which merges React props consistently across the component library:

[[`packages/core/src/utils/mergeProps.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/utils/mergeProps.ts)](https://github.com/facebook/astryx/blob/main/packages/core/src/utils/mergeProps.ts)

### Workspace Configuration

The monorepo is bound together by:

- **[`pnpm-workspace.yaml`](https://github.com/facebook/astryx/blob/main/pnpm-workspace.yaml)** — declares `packages/*` as workspace members
- Root-level [`tsconfig.json`](https://github.com/facebook/astryx/blob/main/tsconfig.json) — shared TypeScript configuration
- Root `scripts/` — build, test, and release automation

## How to Locate Specific Source Files

Follow this decision tree when searching the Astryx source:

1. **UI component** → `packages/core/src/<ComponentName>/<ComponentName>.tsx`
2. **Chart primitive** → [`packages/charts/src/Chart/Chart.tsx`](https://github.com/facebook/astryx/blob/main/packages/charts/src/Chart/Chart.tsx) or sibling files
3. **Vega-Lite wrapper** → [`packages/vega/src/VegaChart.tsx`](https://github.com/facebook/astryx/blob/main/packages/vega/src/VegaChart.tsx)
4. **CLI command** → `packages/cli/astryx.mjs`
5. **Utility function** → `packages/core/src/utils/` or package-specific `utils/`

All source files are browseable directly on GitHub at `facebook/astryx` under the `main` branch.

## Summary

- **All Astryx source files** are in `packages/*/src/` directories within the monorepo
- **Core components** reside in `packages/core/src/` with self-contained component folders
- **Charts and Vega** packages provide specialized visualization sources in their respective `src/` directories
- **Package entry points** are always [`src/index.ts`](https://github.com/facebook/astryx/blob/main/src/index.ts), re-exporting the public API
- **Consuming packages** resolve as `@astryxdesign/<package-name>` (e.g., `@astryxdesign/core`)

## Frequently Asked Questions

### What is the main entry point for Astryx components?

The **core** package at `packages/core/src/` serves as the primary entry point. Most projects import directly from `@astryxdesign/core`, which resolves to this directory. Individual components are then imported by name, such as `import { Button } from '@astryxdesign/core'`.

### How are Astryx components documented?

Each component includes a **`*.doc.mjs`** file located in its component folder. These files contain structured metadata used by the Astryx CLI for documentation generation. The CLI tool itself lives in `packages/cli/astryx.mjs` and consumes these documentation files.

### Can I use individual Astryx packages without the full design system?

Yes. The **monorepo structure** allows independent installation of packages. Install `@astryxdesign/charts` or `@astryxdesign/vega` separately if you only need visualization capabilities. Each package maintains its own dependencies and can be imported standalone.

### Where are Astryx unit tests located?

Unit tests are **co-located with source code**. Each component folder contains a [`ComponentName.test.tsx`](https://github.com/facebook/astryx/blob/main/ComponentName.test.tsx) file adjacent to its implementation. This pattern applies consistently across `packages/core/`, `packages/charts/`, and other source directories.