Turborepo

Overview

Turborepo is a build system engineered to enhance the performance of JavaScript and TypeScript monorepos. Developed and maintained by Vercel, it was founded in 2021 with the goal of improving developer experience in large-scale projects by minimizing build times. It achieves this primarily through two core mechanisms: incremental builds and a content-addressable cache. Incremental builds mean that Turborepo only re-runs tasks for projects that have changed or whose dependencies have changed, rather than rebuilding the entire codebase on every commit or local development cycle.

The content-addressable cache is central to Turborepo's performance optimizations. When a task is executed, Turborepo computes a unique hash based on its inputs (source code, configuration files, environment variables). If an identical set of inputs has been processed before, Turborepo can retrieve the cached output instead of re-executing the task. This caching can be applied locally or distributed across a team and CI/CD pipelines via Turborepo Remote Caching, a cloud-based service. This capability allows build artifacts to be shared, ensuring that a task completed by one developer or CI agent does not need to be re-run by another. This distributed caching model is particularly beneficial for large teams and projects with extensive build processes, as it can significantly reduce the time spent waiting for builds to complete.

Turborepo is primarily suited for organizations managing JavaScript and TypeScript projects within a monorepo structure. It is designed to integrate with existing package managers like npm, Yarn, and pnpm, and can orchestrate various tasks such as building, testing, linting, and deploying applications. Its focus on speed and simplicity aims to reduce friction in developer workflows, making it easier for teams to maintain and evolve large codebases without being hindered by slow build times. While monorepos can offer advantages in code sharing and atomic changes, managing their complexity often requires specialized tooling, a niche Turborepo addresses by streamlining task execution and caching, as discussed in monorepo best practices by developer.mozilla.org on monorepo definitions and benefits.

For teams evaluating monorepo tooling, Turborepo offers an opinionated approach focused on performance. Its command-line interface is designed for ease of use, providing clear output and consistent behavior across different tasks. Turborepo Remote Caching extends the local caching benefits to a collaborative environment, making it a solution for accelerating CI/CD pipelines and ensuring consistent build results across a development team. The local Turborepo CLI is free to use, while the cloud-based remote caching service offers tiered pricing plans, including a free hobby tier.

Key features

• Incremental Builds: Only rebuilds what is necessary, identifying changed files and dependencies to avoid redundant computations (Turborepo incremental builds documentation).
• Content-Addressable Caching: Generates unique hashes for task inputs and stores outputs in a cache, retrieving them if inputs haven't changed.
• Remote Caching: Shares build caches across teams and CI/CD pipelines through a cloud service, reducing duplicate work (Turborepo Remote Caching overview).
• Task Orchestration: Manages and executes tasks (build, test, lint) across multiple packages within a monorepo, understanding their dependencies.
• Parallel Execution: Runs independent tasks in parallel to maximize utilization of available computation resources.
• Pruning: Creates minimal subsets of a monorepo for deployment, including only the necessary dependencies for a specific application (Turborepo pruning documentation).
• Pipeline Configuration: Defines task dependencies and outputs using a simple turbo.json configuration file.

Pricing

The Turborepo CLI for local development is free. Turborepo Remote Caching offers a free tier for hobby projects and scales with usage for professional and enterprise needs.

For detailed and up-to-date pricing information, refer to the Turborepo pricing and billing documentation.

Common integrations

• npm, Yarn, pnpm: Turborepo works with all major JavaScript package managers to manage dependencies and link packages within a monorepo (Turborepo installation guide).
• Next.js: Often used with Next.js applications in a monorepo to optimize build and deployment processes (Turborepo with Next.js handbook).
• Vercel (Deployment): Seamless integration with Vercel's deployment platform, leveraging remote caching for faster deployments of monorepo projects.
• TypeScript: Fully supports TypeScript projects, identifying changes in .ts files and their compiled outputs for caching.
• ESLint, Prettier, Jest: Orchestrates common development tasks like linting, formatting, and testing across monorepo packages.

Alternatives

• Nx: A monorepo toolkit that offers similar task orchestration and caching capabilities, with a strong focus on code generation and plugin extensibility.
• Lerna: A long-standing tool for managing JavaScript monorepos, primarily focused on package publishing and dependency management, with recent re-engagement by Nx maintainers.
• pnpm Workspaces: The built-in monorepo solution for the pnpm package manager, providing efficient dependency management and linking for monorepos.

Getting started

To initialize a new Turborepo project with a basic structure, you can use create-turbo:

npx create-turbo@latest my-turborepo
cd my-turborepo
pnpm install # or npm install / yarn install
pnpm dev

This command sets up a monorepo with example applications and packages. Once inside the project, the turbo.json file configures how tasks are run. For instance, to define a build pipeline:

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

Then, you can run tasks across your monorepo, for example:

pnpm turbo run build

This command will execute the build script for all packages in your monorepo that define one, respecting the dependencies specified in pipeline.build.dependsOn and leveraging caching for outputs.