---
title: Tooling
description: The developer toolchain - pnpm, Nx, vite-plus, and the testing conventions that keep the monorepo predictable.
---

The repository is a pnpm workspace orchestrated by Nx, with vite-plus (vp) as the developer-experience toolchain for linting, testing, formatting, and typechecking. This section documents how it fits together.

<CardGroup cols={3}>
  <Card title="Nx and pnpm" href="/tooling/nx-and-pnpm" icon="package">
    Workspaces, the dependency catalog, tasks, and caching.
  </Card>
  <Card title="vite-plus" href="/tooling/vite-plus" icon="zap">
    The vp commands that run quality gates.
  </Card>
  <Card title="Testing" href="/tooling/testing" icon="shield-check">
    Effect-aware tests, PGlite, and the strongest-invariant rule.
  </Card>
</CardGroup>

Africa OS deliberately keeps its toolchain small: pnpm for packages, Nx for task orchestration, and vite-plus for the quality gates.

```mermaid
flowchart LR
    Pnpm["pnpm - packages"]
    Nx["Nx - task orchestration"]
    Vp["vite-plus (vp) - lint / test / typecheck / format"]
    Scripts["pnpm dev / build / test / lint"]
    Quality["per-package quality gates"]

    Scripts --> Nx
    Nx --> Quality
    Pnpm --> Nx
    Vp --> Quality
```

- **pnpm** owns the dependency graph: workspaces, the catalog, and the lockfile. It is the package manager for the entire repository. The pinned version is `pnpm@11.20.0` (enforced by `packageManager` in the root `package.json`).
- **Nx** owns running tasks across the workspace: it understands the dependency graph, caches results, and runs only what changed. Root scripts like `pnpm dev` delegate to Nx.
- **vite-plus** (aliased as `vp`) owns the per-package quality gates: linting, tests, typechecking, and formatting. Every package's `lint`, `test`, and `typecheck` scripts call `vp`.
- **tsx** runs the infrastructure scripts under `infra/database/scripts` (exposed as `pnpm db:*`).

### The rule of thumb

Use `vp` (or the pnpm scripts that wrap it) for installs, builds, tests, linting, and typechecking - not raw tool binaries. Keep shared tool versions in the catalog so every package stays on the same toolchain.

### Quality expectations

The project's standards live in `.patterns/` at the repository root - read `docs.md` and `testing.md` before writing or changing docs and tests. The two hard rules that touch the toolchain:

- **Always use `pnpm`** - never `npm` or bare `yarn`.
- **Always use `vp`** for installs, builds, and test/lint/typecheck runs rather than calling the underlying binaries directly.

### Database scripts

Database chores are plain `tsx` scripts under `infra/database/scripts`, exposed as root `pnpm db:*` commands. See [Migrations](/database/migrations) for how they work.

| Command | Script |
| --- | --- |
| `pnpm db:migrate` | `infra/database/scripts/migrate.ts` |
| `pnpm db:seed` / `db:seed:production` | `infra/database/scripts/seed.ts` |
| `pnpm db:register-apps` | `infra/database/scripts/register-apps.ts` |
| `pnpm db:seed:admin` | `infra/database/scripts/seed-admin.ts` |
| `pnpm db:verify:org` | `infra/database/scripts/verify-org.ts` |