turbo

Turborepo is a high-performance build system for JavaScript and TypeScript codebases.

weekly downloads8.7M

versionv2.8.10

licenseMIT

categorytoolchain

Overview

Turborepo is a build system designed to optimize task execution in JavaScript and TypeScript monorepos. It addresses the performance bottlenecks that emerge when managing multiple interconnected packages by intelligently caching build outputs, parallelizing tasks across CPU cores, and skipping work that hasn't changed. Unlike traditional task runners that rebuild everything or rely on timestamp checks, Turborepo fingerprints file contents and maintains a dependency graph to determine exactly what needs to run.

The tool emerged from the need to handle complex monorepo workflows at scale. When a codebase contains dozens of packages with interdependencies, running all tests or builds sequentially becomes prohibitively slow. Turborepo solves this by executing tasks topologically—respecting package dependencies—while running independent tasks simultaneously. Its remote caching capability means teams share build artifacts, so CI environments can restore cached outputs instead of rebuilding code that another developer or pipeline already processed.

Developed by Vercel and integrated into their ecosystem, Turborepo has gained traction in production environments handling large-scale applications. With over 8.7 million weekly downloads, it's adopted by teams running Next.js applications, component libraries, and full-stack monorepos. The tool requires minimal configuration—a turbo.json file defining task inputs, outputs, and dependencies—and works alongside existing package managers like pnpm, npm, or Yarn without replacing them.

Turborepo targets teams experiencing slow CI pipelines, developers waiting minutes for local builds, or engineers managing deployments where only a subset of packages changed. It doesn't add runtime overhead to applications and operates purely as a build-time orchestration layer, making it suitable for projects where incremental improvements to developer velocity justify the configuration investment.

Quick Start

typescript

// turbo.json - Define tasks and their dependencies
{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"],
      "inputs": ["src/**/*.ts", "src/**/*.tsx", "package.json"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**/*.ts", "test/**/*.test.ts"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    }
  }
}

// package.json (root) - Add turbo scripts
{
  "name": "my-monorepo",
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "dev": "turbo run dev --parallel"
  },
  "devDependencies": {
    "turbo": "^2.8.10"
  }
}

// packages/web/package.json - Individual package script
{
  "name": "@myorg/web",
  "scripts": {
    "build": "next build",
    "dev": "next dev",
    "test": "vitest run"
  }
}

// Run from monorepo root:
// npx turbo run build --filter=@myorg/web --graph
// This builds only @myorg/web and its dependencies, showing the task DAG

// Enable remote caching:
// npx turbo login
// npx turbo link
// Subsequent runs share cache across team members and CI

Use Cases

Monorepo CI optimization: A repository with 20 packages runs tests on every commit. Without Turborepo, all test suites execute even when changes affect one package. With Turborepo's caching and task scheduling, only affected packages rebuild, reducing CI time from 15 minutes to under 3 minutes for typical pull requests.

Shared component library development: A design system monorepo contains UI components, documentation, and Storybook. Developers run turbo run build lint test locally, and Turborepo executes these tasks in parallel across packages while caching outputs. When switching branches, cached results restore instantly if file hashes match, eliminating redundant rebuilds.

Selective microservice deployment: A monorepo houses five backend services. Using turbo prune --scope=api-gateway, you extract only the api-gateway package and its dependencies into a deployment artifact. This reduces Docker image size and deployment time by excluding unrelated services.

Local development with dependent packages: When working on a shared utilities package that three apps depend on, Turborepo automatically rebuilds those apps when the utility changes. The dependsOn configuration ensures builds happen in the correct order without manual intervention.

Team collaboration with remote caching: Multiple developers work on the same monorepo. After linking to Vercel's remote cache with turbo link, when one developer builds a package, others fetch those cached artifacts instead of rebuilding locally. This is especially valuable for expensive operations like TypeScript compilation or bundling large assets.

Pros & Cons

Pros

+Content-based caching with cryptographic fingerprinting eliminates false cache hits and correctly invalidates outdated builds, unlike timestamp-based systems
+Parallel task execution with topological scheduling maximizes CPU utilization while respecting package dependencies, significantly reducing build times
+Zero runtime footprint—operates purely at build time without modifying application code, sourcemaps, or bundle sizes
+Simple configuration through turbo.json with sensible defaults; no need to rewrite existing package.json scripts
+Remote caching via Vercel infrastructure allows teams to share build artifacts across machines and CI environments

Cons

−Requires Vercel account for remote caching features; self-hosted caching needs third-party solutions or custom infrastructure
−Learning curve for correctly configuring inputs/outputs and task dependencies, especially in complex monorepos with implicit file dependencies
−Limited value in small projects or single-package repositories where native npm scripts and simple CI pipelines suffice
−Cache invalidation can be overly aggressive if file hashing includes frequently changing files like lockfiles or auto-generated code
−Debugging cache misses or unexpected task executions requires understanding of fingerprinting logic and dependency graphs

Alternatives

lernav9.0.4

Lerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository

toolchainlernamonorepo

1.6M / week

nxv22.5.1

The core Nx plugin contains the core functionality of Nx like the project graph, nx commands and task orchestration.

toolchainMonorepoAngular

8.7M / week

Comparisons

Install

bash

npm install turbo

bash

pnpm add turbo

bash

bun add turbo

Overview

Quick Start

typescript

// turbo.json - Define tasks and their dependencies
{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"],
      "inputs": ["src/**/*.ts", "src/**/*.tsx", "package.json"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**/*.ts", "test/**/*.test.ts"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    }
  }
}

// package.json (root) - Add turbo scripts
{
  "name": "my-monorepo",
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "dev": "turbo run dev --parallel"
  },
  "devDependencies": {
    "turbo": "^2.8.10"
  }
}

// packages/web/package.json - Individual package script
{
  "name": "@myorg/web",
  "scripts": {
    "build": "next build",
    "dev": "next dev",
    "test": "vitest run"
  }
}

// Run from monorepo root:
// npx turbo run build --filter=@myorg/web --graph
// This builds only @myorg/web and its dependencies, showing the task DAG

// Enable remote caching:
// npx turbo login
// npx turbo link
// Subsequent runs share cache across team members and CI

Use Cases

Pros & Cons

Pros

+Content-based caching with cryptographic fingerprinting eliminates false cache hits and correctly invalidates outdated builds, unlike timestamp-based systems
+Parallel task execution with topological scheduling maximizes CPU utilization while respecting package dependencies, significantly reducing build times
+Zero runtime footprint—operates purely at build time without modifying application code, sourcemaps, or bundle sizes
+Simple configuration through turbo.json with sensible defaults; no need to rewrite existing package.json scripts
+Remote caching via Vercel infrastructure allows teams to share build artifacts across machines and CI environments

Cons

−Requires Vercel account for remote caching features; self-hosted caching needs third-party solutions or custom infrastructure
−Learning curve for correctly configuring inputs/outputs and task dependencies, especially in complex monorepos with implicit file dependencies
−Limited value in small projects or single-package repositories where native npm scripts and simple CI pipelines suffice
−Cache invalidation can be overly aggressive if file hashing includes frequently changing files like lockfiles or auto-generated code
−Debugging cache misses or unexpected task executions requires understanding of fingerprinting logic and dependency graphs