Turborepo - Make Your Monorepo Builds Not Suck

Look, if you've worked with a JavaScript monorepo for more than five minutes, you know the pain. Your build went from 30 seconds to "time for a coffee break" once you hit three packages. By package ten, you're questioning your life choices. Every change triggers a complete rebuild of everything, even if you just fixed a typo in a fucking README.

This isn't just a theoretical problem - I've watched Netflix engineers tweet about 4-hour builds while Facebook wrote a whole paper about how they had to invent Buck just to compile React without losing their minds.

Jared Palmer got fed up with this same bullshit and built Turborepo. Vercel bought it in 2021 because even they were tired of waiting for their own builds.

Why Your Current Build Setup Sucks

Everything rebuilds every time
Change one line in your utils package? Congratulations, you just triggered a rebuild of your entire frontend, backend, and documentation site. Hope you like waiting.

Zero parallelization
Most setups run builds sequentially like it's 1995. Got 8 cores? Too bad, you're using one and heating up your laptop for no reason.

No caching worth a damn
Oh, you changed a comment? Better rebuild everything from scratch because your build system has the memory of a goldfish.

What Turborepo Actually Does About It

Smart dependency tracking
Turborepo builds a dependency graph of your packages and only rebuilds what actually changed. Like Bazel and Nx, but without the 500-page configuration manual.

Modify your button component? It rebuilds the button package and the apps that use it, not the 12 other packages that don't give a shit. In practice, this means builds that took 20 minutes now take maybe 3-4 minutes. Sometimes the cache breaks and you're back to square one, but hey, at least it tries.

Task-level caching that mostly works
The cache stores build outputs and checks file hashes to decide if anything changed. Change nothing? Zero-second builds. This works great until it doesn't, and you'll spend a weekend figuring out why your cache thinks everything is dirty.

Parallel execution (when it works)
Uses all your CPU cores like a modern build system should. The build output can be a mess when multiple things are building at once, but at least it's fast. You can dial down the concurrency if your laptop starts sounding like a jet engine.

The Technical Details

Built in Rust because apparently every build tool needs to be rewritten in Rust to be taken seriously these days. They rewrote it from Go to Rust in 2022, which tells you everything about JavaScript tooling priorities - let's spend six months porting instead of fixing the cache bugs everyone's complaining about.

It does the usual stuff - builds dependency graphs, schedules tasks, caches outputs, watches for file changes. The remote caching works with S3, Google Cloud, Azure, or whatever blob storage you're already paying for.

Most importantly, you don't have to rewrite your entire build system in some new DSL that'll be abandoned next year. The config is just JSON.

This incremental adoption approach is what sets Turborepo apart from more invasive solutions. Version 2.4 added terminal UI improvements and watch mode caching, while earlier versions introduced experimental boundaries to catch monorepo mistakes before they break your cache. Because apparently developers can't be trusted to follow their own conventions.

Bottom line: if you're drowning in JavaScript build times and don't want to spend three weeks configuring Bazel, Turborepo is probably your best shot at sanity. Check out the complete performance benchmarks comparing it to Nx and other tools.

Installation: The Easy Part

npm install turbo --save-dev

That's it. Don't install it globally unless you enjoy the classic "works on my machine but not in CI" debugging sessions. The official installation guide covers other package managers if you're using pnpm or yarn.

Configuration: Where It Gets Real

You need a `turbo.json` in your root. Here's the minimal setup that actually works:

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

Key gotchas:

• The `^build` syntax means "wait for dependencies to build first"
• You MUST specify `outputs` or caching won't work
• dev should be `persistent: true` or it'll kill your dev server
• Missing the schema URL means no autocomplete (and you'll hate configuring this)
• Environment variables need to be declared in globalEnv or env

Remote Caching: The Part That Costs Money

If you're on Vercel, remote caching is free for personal projects. For teams, it's $20/month per developer because someone at Vercel decided caching should cost more than your entire database.

Set it up:

turbo login
turbo link

The `turbo login` command opens a browser to authenticate with Vercel, while `turbo link` connects your repository to the remote cache.

Now your cache is shared across the team and CI. When it works, it's magic. When it doesn't, you'll debug cache invalidation issues for hours. The Vercel dashboard shows cache hit rates and team usage.

Non-Vercel options:

• AWS S3 (setup is a pain, but cheap storage)
• Google Cloud Storage (slightly less painful setup)
• Azure Blob Storage (if you're already on Azure)
• Nx Cloud (works with Turborepo via custom remote cache)
• Your own S3-compatible storage like MinIO (good luck)

What Actually Happens When You Run It

turbo run build

Turborepo will:

1. Figure out which packages changed
2. Build dependencies first (if needed)
3. Run builds in parallel when possible
4. Cache everything (probably)

Useful flags you'll actually use:

• `--filter=changed` - only build what changed since last commit
• `--dry-run` - see what it would do without executing
• `--force` - ignore cache (when cache is being stupid)
• `--no-cache` - disable caching entirely
• `--only` - skip dependencies and only run the specified packages
• `--continue` - keep going even if one task fails

The Reality of Implementation

Most teams just YOLO it into production and pray. Builds get faster? Ship it. Builds break? Well, that's what weekends are for, right?

Common setup issues:

• Forgetting to specify outputs - your cache will be empty and you'll waste hours wondering why
• Not handling environment variables in cache keys - builds will use wrong env
• Windows path issues if you have Windows developers (just use WSL2)
• Cache corruption that happens about once a week and requires manual cleanup (and rage-quitting)
• pnpm workspace configuration not matching Turborepo expectations
• TypeScript project references breaking when packages aren't built in order
• File watching issues in large monorepos - errors like `ENOSPC: System limit for number of file watchers reached`
• Node 18.2.0 specifically breaks with ERR_OSSL_EVP_UNSUPPORTED - stick with 18.1.0 or 18.3.0+

Time investment reality:

• 30 minutes if your setup is simple
• 3 hours if you have custom build scripts
• A full weekend if you hit weird edge cases (and you fucking will, because this is JavaScript)
• Two weeks if you have Docker + Windows developers + custom TypeScript configs

The 65-85% build time improvement numbers are real, but only if you configure it correctly and your cache doesn't randomly break. I've seen builds go from 15 minutes to 2 minutes after a weekend of configuration tweaking.

What I didn't mention is the three days you'll spend googling "turborepo cache not working" while your teammates ask why the builds are slower than before you "fixed" them. Check out this troubleshooting guide when (not if) things break.