Turborepo: Monorepos That Actually Scale

The WPDeveloper plugin suite — BetterDocs, NotificationX, SchedulePress, BetterLinks, and a few smaller ones — shared a monorepo with shared UI components, shared TypeScript types, and shared tooling. Clean builds were taking close to 8 minutes by the time we had ~12 plugins in there, which meant CI was the bottleneck on PR feedback. Adding Turborepo with remote caching dropped warm-cache builds to about 40 seconds. That changed how the team worked — PRs got reviewed faster, hotfixes went out faster, and we stopped scheduling builds around lunch breaks.

Monorepos promise shared code, unified tooling, and atomic changes across packages. They deliver — until the repo grows large enough that builds take 10 minutes and CI costs spiral. Turborepo is a build orchestrator designed to keep monorepos fast as they scale, using aggressive caching and dependency-aware task graphs.

The Caching Model

Turborepo caches the output of every task keyed on the task inputs — source files, dependencies, and config. If nothing relevant has changed, the task is skipped entirely and its cached output is restored. This turns most CI runs into glorified cache restores.

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**", "tests/**"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "inputs": ["src/**", ".eslintrc*"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Remote Caching

Local caching helps a single developer. Remote caching helps an entire team. When one engineer builds a package, the cache uploads to a shared store. Every other engineer — and every CI run — can restore that cache instead of rebuilding. Cold CI runs become warm.

# Link your repo to Vercel for free remote caching
npx turbo login
npx turbo link

# Or self-host with the open-source server
# https://turbo.build/docs/cache/self-hosted

# Run with remote cache enabled
turbo run build

Filter and Scope

Turborepo can run tasks only for packages affected by your changes. Combine filters with git to build exactly what changed in a PR, not the entire repo.

# Build only the web package
turbo run build --filter=web

# Build web and everything it depends on
turbo run build --filter=web...

# Build everything that depends on the ui package
turbo run build --filter=...ui

# Build only packages changed since main
turbo run build --filter=[origin/main]

# In CI — build everything affected by the PR
turbo run build test --filter=[HEAD^1]

Recommended Repo Structure

The de-facto standard for Turborepo monorepos is an apps/ directory for runnable projects and a packages/ directory for shared code. This maps cleanly to most workflows and keeps the task graph interpretable.

my-monorepo/
├── apps/
│   ├── web/           # Next.js app
│   ├── docs/          # Astro docs site
│   └── mobile/        # React Native app
├── packages/
│   ├── ui/            # Shared component library
│   ├── config-eslint/ # Shared ESLint config
│   ├── config-tsconfig/
│   └── core/          # Shared business logic
├── turbo.json
├── package.json
└── pnpm-workspace.yaml

pnpm vs npm vs yarn

Turborepo works with any workspace-aware package manager, but pnpm has become the consensus choice. It installs faster, uses less disk, and its strict node_modules layout catches phantom dependencies that npm hoisting would hide.

Measuring the Win

For a medium monorepo (20 packages, 100k lines), typical numbers after adopting Turborepo with remote caching: CI build time drops from 8 minutes to 90 seconds on cache hits. Local turbo run test goes from 45 seconds to instant when you have not touched anything. The compounding effect on developer productivity is dramatic.

Common Pitfalls

• Forgetting to declare outputs in turbo.json — tasks run but their artifacts are not cached
• Missing files in inputs — cache hits when you should have rebuilt (silent incorrectness)
• Overly broad inputs — cache invalidates too easily, defeating the point
• Relying on untracked environment variables — declare them with passThroughEnv
• Running persistent tasks (dev servers) through turbo run in CI — use watch mode instead

Conclusion

On the WPDeveloper plugin monorepo, getting the Turborepo config right took a couple of iterations — we had a few packages with sloppy "inputs" declarations that were invalidating caches more than necessary. Once we tightened those up, the cache hit rate went above 80% on regular CI runs. The key insight is that the cache is only as good as your config: be honest about what each task actually depends on, and the speedup is so significant it feels like cheating. After this migration I reach for Turborepo on every monorepo I touch.