Monorepo Architecture: Managing Multiple Projects at Scale

A monorepo contains multiple projects (apps, packages, libraries) in a single repository. Google, Meta, and Microsoft use monorepos at massive scale. For smaller teams, monorepos simplify code sharing and dependency management.

When to use a monorepo: multiple related applications sharing code (web app, mobile app, admin dashboard), shared component libraries, or microservices that need coordinated deployments and consistent versioning.

Monorepo tools: Turborepo (simple, fast, Vercel-backed), Nx (feature-rich, opinionated), and Lerna (legacy, now maintained by Nx). Turborepo is the best starting point for most JavaScript/TypeScript monorepos.

Workspace structure: apps/ for deployable applications, packages/ for shared libraries, and a root package.json with workspace configuration. Each package has its own package.json defining dependencies and scripts.

Shared packages: component libraries (ui/), utility functions (utils/), configuration (tsconfig/, eslint-config/), and type definitions (types/). Internal packages use workspace protocols (workspace:*) for versioning.

Build caching: Turborepo caches build outputs based on input hashes. If source files have not changed, builds are skipped entirely. Remote caching (Vercel) shares cache across team members and CI.

Task orchestration: define task dependencies (build depends on type-check) and Turborepo runs them in optimal parallel order. This ensures correct build ordering while maximizing CPU utilization.

CI/CD for monorepos: run tests and builds only for affected packages. Turborepo's --filter flag targets specific packages. Combined with remote caching, CI runs are fast even as the monorepo grows.

Dependency management: keep dependencies consistent across packages. Use a tool like syncpack to ensure the same version of React, TypeScript, and other shared dependencies across all packages.

Common challenges: initial setup complexity, longer git clone times (use sparse checkout), and the learning curve for monorepo tooling. These are manageable and outweighed by the benefits for teams with shared code.