Turborepo — High-Performance Monorepo Build System

Introduction

Turborepo is a high-performance build system for JavaScript and TypeScript monorepos, now maintained by Vercel. It solves the fundamental challenge of monorepo development: as your codebase grows with multiple packages and apps, build times grow linearly. Turborepo makes builds incremental — only rebuilding what changed.

With 30,000+ GitHub stars, Turborepo has been adopted by companies like Vercel, Netflix, and AWS for managing their monorepo workflows. Written in Rust (rewritten from Go), it provides intelligent caching, parallel task execution, and remote cache sharing across teams.

What Turborepo Does

Turborepo sits on top of your existing package manager (npm, pnpm, yarn) and orchestrates task execution across packages. It understands the dependency graph between your packages and runs tasks in the optimal order, caching results so unchanged packages are never rebuilt.

Architecture Overview

[turbo.json] --> [Task Pipeline Definition]
                        |
              [Dependency Graph Analysis]
              Reads package.json files
              across all workspaces
                        |
           +------------+------------+
           |            |            |
     [Package A]   [Package B]  [Package C]
     build         build         build
     (cached)      (run)         (depends on B)
           |            |            |
           +------------+------------+
                        |
              [Local or Remote Cache]
              Hash-based: inputs -> outputs
              Share cache across CI and team

Self-Hosting & Configuration

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

// Root package.json
{
  "workspaces": ["apps/*", "packages/*"],
  "devDependencies": {
    "turbo": "^2.0.0"
  },
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "test": "turbo test"
  }
}

Key Features

• Incremental Builds — never redo work that has already been done
• Content-Aware Hashing — cache based on file contents, not timestamps
• Parallel Execution — run tasks across packages simultaneously
• Remote Caching — share cache across CI runs and team members
• Task Pipelines — define relationships between tasks with dependsOn
• Pruned Subsets — generate minimal monorepo subsets for Docker builds
• Watch Mode — re-run tasks automatically when source files change
• Dry Run — preview what tasks would run without executing them

Comparison with Similar Tools

FAQ

Q: Turborepo vs Nx — which should I choose? A: Turborepo is simpler and faster to set up — it focuses on task orchestration and caching. Nx offers more features like generators, migration tools, and framework-specific plugins. Choose Turborepo for simplicity, Nx for a full-featured monorepo platform.

Q: Does Turborepo replace npm/pnpm workspaces? A: No. Turborepo works alongside your package manager workspaces. It orchestrates task execution and caching on top of whatever workspace tool you already use.

Q: How does remote caching work? A: Turborepo hashes your task inputs and checks a remote cache (Vercel by default, or self-hosted) before running. If a matching hash exists, it downloads the cached outputs instead of rebuilding — saving minutes per CI run.

Q: Can I use Turborepo without a monorepo? A: Yes, but the benefits are minimal. Turborepo shines when orchestrating tasks across multiple packages. For single-package repos, a simple build script is usually sufficient.

Sources

• GitHub: https://github.com/vercel/turborepo
• Documentation: https://turbo.build
• Created by Jared Palmer, maintained by Vercel
• License: MIT