Turborepo in 2026: a complete guide to fast monorepos

What Turborepo is, and when to use it.

Turborepo solves one specific problem: running the same task graph across multiple packages in a monorepo, fast, without redoing work you have already done. If you have two apps and three shared packages, and every push to main rebuilds all of them from scratch, you are wasting minutes on every commit. Turborepo caches task outputs by content hash. Change a single file in packages/ui, and only the packages that depend on ui get rebuilt.

Use it when you have three or more packages sharing config, and at least two apps consuming them. Skip it for single-package repos; the overhead is not worth it. Skip it for polyglot monorepos with Rust or Go alongside Node; Turborepo is Node-first and does not orchestrate non-JS task graphs well. For those, look at Bazel or Nx.

Installing Turborepo.

Assumes you already have pnpm and a workspaces root:

pnpm add turbo --save-dev --workspace-root
pnpm exec turbo login

Now add a turbo.json at the root, next to pnpm-workspace.yaml.

Your first turbo.json.

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "lint": {},
    "test": {
      "dependsOn": ["^build"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

dependsOn: ["^build"] tells Turborepo that the current package’s build task depends on its dependencies being built first. The caret means “upstream”. outputs tells Turborepo which paths to snapshot into the cache. persistent: true is the dev-server flag; Turborepo will not treat it as complete and will not try to cache its output.

Remote caching.

Local caching is free and instant. Remote caching is where the compounding wins arrive: your CI builds the packages once, uploads the artifacts, and every developer on your team gets the cache hit locally. Vercel Remote Cache is free for open source and included in the paid tier for teams. Self-hosted alternatives include Turbo Remote Cache Server (open source, run on Fly.io or Vercel Functions) and Cloudflare Workers-based mirrors.

A worked example.

Here is the layout that ships on the majority of Turborepo projects we have built for clients this year:

.
├── apps
│   ├── web         # Next.js 15
│   └── docs        # Astro 5
├── packages
│   ├── ui          # shared React components + Tailwind preset
│   ├── config      # tsconfig, eslint, prettier
│   └── db          # Prisma client + schema
├── pnpm-workspace.yaml
├── turbo.json
└── package.json

Performance benchmarks.

Tested on an M2 Air, cold cache vs warm cache, 3-package repo (ui, config, db) with two apps (Next.js + Astro):

• Cold build all: 1m 47s
• Warm build all: 3.2s (cache hit on every task)
• Change one file in packages/ui: 18s (rebuilds ui + web + docs, caches config + db)
• Change one file in apps/web: 9s (rebuilds web only)

Turborepo vs Nx vs Rush.

Nx is a superset: task orchestrator plus code generators, plugin surface, and a workspace inspector UI. Nx is right if you want the full plugin surface (Angular, NestJS, Cypress code-gen). Turborepo is right if you want just the fast task graph and cache, nothing else. Rush from Microsoft is the enterprise choice: strict, opinionated, deeply integrated with Azure DevOps. Rare outside Microsoft-shop teams.

Common pitfalls.

• Forgetting to add generated files (Prisma client, tRPC types) to outputs. Cache hits, but the app fails at runtime because the generated files were not restored.
• Using dependsOn: ["build"] instead of dependsOn: ["^build"]. The caret is the difference between “my build depends on my dependencies’ builds” and “my build depends on my own build” (which is a no-op).
• Setting cache: false everywhere. You lose the entire point of the tool. Only dev and other persistent tasks need it.
• Not passing environment variables through globalEnv. A cache hit on the wrong NEXT_PUBLIC_API_URL will ship the wrong bundle to production.

FAQ.

Is Turborepo free?

Turborepo itself is MIT-licensed and free. Vercel Remote Cache is free for open source and Hobby, paid for teams of eleven or more.

Does Turborepo work with Yarn or npm?

Yes, but pnpm is the recommended pairing. The workspace-linking behaviour is more predictable, and pnpm’s content-addressable store means you get another layer of dedup below Turborepo’s cache.

Can Turborepo replace CI?

No. Turborepo runs your task graph; CI still orchestrates when and where. What Turborepo does is make each CI run 10 to 100 times faster on a warm cache.