Skip to content

0004. Nx monorepo

  • Status: Accepted
  • Date: 2026-10-01

Context

BizOS has several apps (API, worker, tenant web app, admin portal) and shared packages in one repository, built with React and NestJS in TypeScript. We need fast builds as the code grows, one consistent way to generate and run projects, and tooling that enforces the module boundaries defined in STACK.md.

Options considered

  1. pnpm workspaces only: minimal, but no task caching, no affected detection, and no boundary rules.
  2. Turborepo: fast task caching, but no code generators and no module boundary enforcement.
  3. Nx: task caching, affected commands for CI, first-party generators for React and NestJS, a project graph, and the @nx/enforce-module-boundaries lint rule driven by project tags.

Decision

Use Nx on top of pnpm workspaces as the monorepo tool. Add Nx plugins (@nx/react, @nx/nest, and others) when the corresponding apps are scaffolded.

Consequences

  • CI runs only what a change affects (nx affected), and local builds reuse cached results.
  • Module boundaries from the DDD design are enforced by lint through project tags.
  • Nx and its plugins must be upgraded together with nx migrate.
  • Nx Cloud is not used; caching is local unless decided otherwise in a later ADR.