Scaling Monorepos with Turborepo

Why Monorepos Break Down Without Tooling

A monorepo starts simple: two packages, fast builds, easy sharing. Then it grows. Six packages, twelve packages. Suddenly npm run build in the root takes four minutes because it rebuilds every package every time, even the ones that haven't changed.

This is the problem Turborepo was built to solve.

The Task Graph

Turborepo models your monorepo as a task graph — a directed acyclic graph where nodes are tasks and edges are dependencies between them.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^lint"]
    }
  }
}

The ^ prefix means "run this task in all dependencies first." So when you run turbo build in a monorepo where web depends on ui and utils, Turbo:

1. Builds utils (no dependencies)
2. Builds ui (depends on utils)
3. Builds web (depends on both)

And it does this with maximum parallelism — tasks that don't depend on each other run concurrently.

Caching: The Real Win

The graph is clever. The cache is transformative.

Turbo hashes the inputs of every task: source files, environment variables, lock files, task configuration. If the hash matches a previous run, Turbo replays the output instantly — it doesn't run the task at all.

# First run: builds everything (4m 12s)
turbo build

# Second run, nothing changed: replays from cache (1.3s)
turbo build
>>> FULL TURBO (cache hit)

Remote caching extends this to your entire team and CI. Once a teammate builds a package, everyone else gets the cached output. A fresh CI run on a PR that only touches web doesn't rebuild ui — it fetches the cached artifact from Vercel Remote Cache or your own S3 bucket.

Workspace Structure That Scales

The package structure that works well in practice:

apps/
  web/          # User-facing app (Next.js, Astro, etc.)
  cms/          # Admin/CMS app
packages/
  ui/           # Shared React components
  typescript-config/  # Shared tsconfig bases
  eslint-config/      # Shared ESLint configs

Packages in packages/ should be internal-only by default ("private": true). They're not published to npm; they're consumed directly by apps via workspace references:

{
  "dependencies": {
    "@repo/ui": "workspace:*"
  }
}

Common Mistakes

Putting too much in one package. If a package has 50 components and you change one, the entire package's cache is invalidated. Split by domain, not by size.

Not specifying outputs. Without outputs defined, Turbo can't cache build artifacts. Every task that produces files needs an outputs entry.

Using dependsOn: ["build"] instead of ["^build"]. The former depends on the build task in the same package. The latter depends on build in all dependencies — which is almost always what you want.

The Pipeline Mental Model

Think of your monorepo tasks like a pipeline in a factory. Raw inputs (source code) flow through stages (lint → type-check → build → test) with shared components built once and reused everywhere. Turborepo's job is to run that pipeline as fast as physics allows, skipping any stage where the inputs haven't changed.

Once you internalize this mental model, the configuration becomes intuitive and debugging cache misses becomes methodical.