Nx and pnpm

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:

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:

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

The dependency catalog

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

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::

{
  "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:

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:

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

Affected-only (before pushing a branch):

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.