Pattern: Monorepo structure and tooling

Managing multiple related packages/services in separate repos leads to dependency hell, version mismatches, and difficult cross-project changes.

Organize related code in a single repo with proper tooling:

Project structure:
monorepo/
packages/
shared/ # Shared types, utils
ui/ # Component library
api-client/ # API client SDK
apps/
web/ # Next.js frontend
api/ # Express backend
admin/ # Admin dashboard
package.json # Root with workspaces
turbo.json # Build orchestration

// Root package.json (npm/pnpm workspaces):
{
"workspaces": ["packages/", "apps/"]
}

// pnpm-workspace.yaml (pnpm):
packages:
- 'packages/*'
- 'apps/*'

Tooling:

• Package manager: pnpm (best for monorepos) or npm workspaces
• Build orchestrator: Turborepo or Nx

- Caches build outputs
- Only rebuilds what changed
- Parallel execution with dependency awareness

• Versioning: changesets for publishing packages

// turbo.json:
{
"tasks": {
"build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
"test": { "dependsOn": ["build"] },
"lint": {}
}
}

Benefits:

• Atomic cross-package changes (one PR)
• Shared tooling config (ESLint, TS, prettier)
• Always-compatible versions between packages
• Easier code reuse and refactoring

Monorepos eliminate version mismatch issues and enable atomic cross-project changes, while modern tooling handles the build complexity.