# Set up the monorepo

> Clone the Azmara Platform repository, build every package and run the docs site locally. For contributors; to use @azmr/ui in your own app, see Installation.

Source: https://platform.azmara.io/docs/guide/monorepo-setup

This page is for working on the packages themselves. To use `@azmr/ui` in an app, follow [Installation](https://platform.azmara.io/docs/guide/installation.md) instead.

## Prerequisites

- Node.js >= 20.0.0
- pnpm >= 9.0.0
- **For `@azmr/ai`**: Visual Studio 2022 with "Desktop development with C++" workload

## Clone & install

```bash
git clone https://github.com/azmara-labs/platform.git
cd platform
pnpm install
```

## Environment setup

```bash
cp .env.example .env
```

Fill in the required values:

```bash
# Generate an encryption key
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

## Build all packages

```bash
pnpm build
```

## Try the playground

```bash
pnpm --filter @azmr/site dev
```

Then open `/playground` — a live, interactive demo of `@azmr/core`, `@azmr/query`, and `@azmr/ui`
working together, no separate app to run. See the [Playground](https://platform.azmara.io/docs/guide/playground.md) guide for
what it demonstrates.

## Check the docs site

CI checks the docs in four ways beyond the unit tests, and you can run each locally:

- **Links, demos and entry points:** `pnpm --filter @azmr/site test` checks every link and anchor, that every demo exists and renders, and that every package entry has a page.
- **Accessibility of the rendered pages:** build and start the site, then run axe over every page in light and dark mode in Chrome.

  ```bash
  pnpm turbo run build --filter=@azmr/site
  pnpm --filter @azmr/site start &
  pnpm --filter @azmr/site check:pages
  ```

  A violation fails the check. The few we accept are listed with a reason in `apps/site/a11y-known-issues.json`, and a listed issue that stops occurring fails the check too, so remove it.
- **Performance:** Lighthouse (mobile) runs three times on the landing page and on the menu page, and the medians are compared with `apps/site/lighthouse-budgets.json`. Each page has a **target** (the project standards: 96 on every score, FCP under 1.5 s, LCP under 2.5 s, CLS under 0.1) and a **limit**, the worst accepted for now. A page past its limit fails the check; a missed target is reported, so the check tells the truth about the gap without failing every pull request. Tighten a limit as the page improves. Run it with `pnpm --filter @azmr/site check:lighthouse` against the running site. The limits were set from runs on the CI runner, which is steadier than a laptop: a single local run can swing by 20 points, so judge a change by the CI result, or by the median of several local runs. On the CI runner the menu page has two modes, about 3.1 to 3.5 s or 4.4 s, depending on whether the first paint lands before or after the page's JavaScript has loaded; its limit is set from the slower, steadier one, and the way to bring it down is less JavaScript on the docs pages.
- **Spelling:** the docs use New Zealand English, and a test fails on American spellings in prose (`color`, `behavior`, `organize`). Code, link targets and the generated changelogs are not checked.

## Native module note

`@azmr/ai` uses `isolated-vm` which requires native compilation.

**Windows:**

1. Install **Visual Studio 2022** with "Desktop development with C++" workload
2. Run `pnpm rebuild isolated-vm`

**macOS:** Xcode Command Line Tools (`xcode-select --install`)

**Linux:** `sudo apt install build-essential python3`