---
title: Nx and pnpm
description: How the monorepo is managed - pnpm workspaces, the dependency catalog, and Nx task orchestration.
---

Africa OS is a pnpm workspace orchestrated by Nx. This page covers how packages are declared, how versions are pinned, and how tasks are run and cached.

### pnpm workspaces

`pnpm-workspace.yaml` declares the workspace globs:

```yaml
packages:
  - apps/*
  - platform/*
  - packages/*
  - packages/applications/*
  - tooling/*
```

Every folder matching a glob is a workspace member. Packages reference each other with `workspace:*`, which pnpm resolves to the local package:

```json
{
  "dependencies": {
    "@africaos/request-context": "workspace:*"
  }
}
```

### The dependency catalog

Shared tools are pinned once in the catalog so packages never repeat versions:

```yaml
catalog:
  vite: npm:@voidzero-dev/vite-plus-core@0.2.8
  vitest: 4.1.10
  vite-plus: 0.2.8
```

Packages depend on cataloged tools with `catalog:`:

```json
{
  "devDependencies": {
    "vite": "catalog:",
    "vitest": "catalog:",
    "vite-plus": "catalog:"
  }
}
```

The catalog is the single place to change a shared tool version.

### Nx task orchestration

`nx.json` teaches Nx about the workspace's targets and caching:

- **`namedInputs`** - `default` is a project's files plus shared globals; `production` excludes `*.spec.ts`.
- **`targetDefaults`** - per-target inputs, caching, and dependencies. `build` depends on `^build` (the builds of imported packages) and caches by content hash. `dev` is `persistent: true` and `cache: false`.
- **`workspaceLayout`** - apps under `apps/`, libraries under `packages/`.

### Running tasks

From the root:

```bash
pnpm dev            # every app with a dev target, via Nx run-many
pnpm build          # every app with a build target, in dependency order
pnpm typecheck
pnpm test
pnpm lint
pnpm format         # vp fmt .
```

Scoped to a package:

```bash
pnpm --filter @africaos/web dev
pnpm nx run @africaos/retail:test
```

Affected-only (before pushing a branch):

```bash
pnpm nx affected -t typecheck test lint
```

### How caching behaves

Nx caches `build`, `typecheck`, `lint`, and `test` by content hash of their inputs. Unchanged projects are skipped (a cache hit restores the result). `dev` is never cached or restarted automatically. If a cached result is stale, pass `--skip-nx-cache` or force.

### Conventions

- **Never use npm.** Only pnpm.
- **Prefer `vp` for quality gates.** The `lint`/`test` scripts call vite-plus, not raw tools.
- **Add new packages through the workspace globs** - no registration file needed beyond the folder.
- **Keep version bumps in the catalog** when the tool is shared.