Skip to content

ADR-0009: Monorepo with pnpm and Turborepo

  • Status: Accepted
  • Date: 2026-11-12

The system has seven apps (API, worker, office system, driver app, landing site, careers site, documentation) and five packages (database, contract, design system, app base, shared configuration). A typical change touches a migration, a route, the generated client and a screen.

How is the code organized so that such a change is one reviewable unit?

  • A change that crosses the back end, the contract and a screen is one commit.
  • One version of each library across the repository.
  • Build, lint, type check and tests run only where something changed.
  1. One repository with pnpm workspaces and Turborepo.
  2. One repository per app, with the shared packages published to a registry. Common market alternative, listed for comparison.
  3. Another workspace or build tool for a monorepo. Common market alternative, listed for comparison.

Chosen option: 1.

pnpm-workspace.yaml declares apps/*, packages/* and e2e. Library versions are written once, in the pnpm catalog, and each workspace refers to them with catalog:. The pnpm protection that skips releases published less than one day ago stays on. turbo.json declares the tasks build, lint, typecheck and test, each depending on the build of the packages it uses, with cached outputs.

  • Good, because the contract and its consumers change together, and the type check sees both sides.
  • Good, because the catalog makes a library upgrade one line for the whole repository.
  • Good, because Turborepo skips tasks whose inputs did not change.
  • Bad, because an upgrade of a shared library reaches every workspace at once and must pass everywhere.
  • Bad, because a release cannot be adopted on the day it is published.
  • Bad, because the full check grows with the repository. Day-to-day work depends on filters and on the cache.
  • pnpm-workspace.yaml: the workspaces and the catalog.
  • turbo.json: the tasks and their dependencies.
  • packages/config: the shared ESLint, TypeScript and Prettier configuration.
  • Concept page: Testing.
  • Building blocks.