Set up the monorepo

This page is for working on the packages themselves. To use @azmr/ui in an app, follow Installation instead.

PrerequisitesCopy Anchor Link

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

Clone & installCopy Anchor Link

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

Environment setupCopy Anchor Link

cp .env.example .env

Fill in the required values:

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

Build all packagesCopy Anchor Link

pnpm build

Try the playgroundCopy Anchor Link

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 guide for what it demonstrates.

Check the docs siteCopy Anchor Link

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.

  Copy Text

  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 noteCopy Anchor Link

@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