Managing Monorepos with pnpm and Turborepo at Scale

As projects grow beyond a single package, monorepos become both essential and challenging. pnpm and Turborepo together provide a powerful combination: pnpm handles dependency management with content-addressable storage, and Turborepo adds task orchestration with intelligent caching.

Why pnpm

pnpm uses content-addressable storage—packages are stored once on disk in a global store and linked into projects. This eliminates the disk waste of npm or Yarn, where the same version of a package is duplicated across every project. Install times are faster because pnpm parallelizes downloads and avoids re-downloading cached packages.

The workspace protocol (\"@scope/pkg\": \"workspace:*\") lets you reference internal packages by name without version numbers. pnpm resolves these to the local workspace, ensuring all packages use compatible versions.

Why Turborepo

Turborepo adds task orchestration and caching. It reads your dependency graph and parallelizes tasks intelligently: if package A depends on B and C, Turborepo builds B and C in parallel, then builds A. Unchanged packages are skipped when their cached outputs are available.

Setting Up

Configure turbo.json with pipeline definitions. The dependsOn array controls ordering: \"^build\" means "wait for all dependencies to build first." The outputs array tells Turborepo which files to cache.

{
  \"pipeline\": {
    \"build\": {
      \"dependsOn\": [\"^build\"],
      \"outputs\": [\"dist/**\", \".next/**\"]
    },
    \"lint\": {},
    \"test\": {
      \"dependsOn\": [\"build\"]
    }
  }
}

Caching Strategy

Turborepo's remote caching saves build outputs to the cloud. CI pipelines run only the changed packages and their dependents, reducing build times from minutes to seconds for most changes. Use Vercel Remote Caching or set up a custom cache server.

CI/CD Integration

Integrate with GitHub Actions or similar: check out the repo, install pnpm, run pnpm install, then pnpm turbo build lint test. Turborepo detects which packages changed and runs only the affected tasks.

Common Pitfalls

Avoid circular dependencies by using pnpm's --filter to detect workspace reference cycles. Keep shamefully-hoist false to prevent accidental access to undeclared dependencies. When modifying shared configuration packages, ensure the dependency graph accurately captures which packages depend on them so cache invalidation works correctly.