1.6 KiB
ADR-0001: Monorepo with pnpm workspaces and Turborepo
- Status: Accepted
- Date: 2026-08-11
Context
Three deployable applications (storefront, admin, API) share domain types, validation rules and an HTTP client. Split across three repositories, every contract change becomes a version bump, a publish and three coordinated pull requests — and in practice the types drift because nobody wants to pay that cost for a one-field change.
Decision
A single repository with pnpm workspaces for dependency linking and Turborepo for task
orchestration and caching. Shared code lives in packages/*; deployables live in apps/*.
@sport/types, @sport/validation and @sport/api-client compile to CommonJS + .d.ts
because NestJS consumes them at runtime. @sport/ui ships raw TypeScript and is compiled by
each Next.js app via transpilePackages — no build step, no watcher, faster HMR.
Versions that must stay identical across the workspace (TypeScript, React, Next, Zod, ESLint)
are pinned once in the catalog: block of pnpm-workspace.yaml.
Consequences
A backend field rename surfaces as a frontend type error in the same commit. One lockfile, one CI pipeline, one lint configuration. The cost is a heavier initial install and the need for discipline about dependency direction (ADR-0004), which the ESLint boundary rules enforce mechanically.
Alternatives considered
Polyrepo with a private npm registry — rejected: the publish/consume loop is slower than the entire feature it serves. Nx — comparable, but Turborepo's smaller surface fits a team that wants a build cache, not a build framework.