Turborepo

Turborepo is a community skill for managing JavaScript and TypeScript monorepos, covering task pipelines, incremental builds, remote caching, workspace dependencies, and parallel task execution for efficient multi-package development.

What Is This?

Overview

Turborepo provides guidance on building and managing monorepo projects using the Turborepo build system. It covers task pipelines that define build, test, and lint dependencies between workspace packages for correct execution ordering, incremental builds that skip unchanged packages by hashing inputs and comparing against previous build outputs, remote caching that shares build artifacts across team members and CI environments through cloud-hosted cache storage, workspace dependency management that resolves internal package references and ensures consistent version resolution, and parallel task execution that runs independent tasks concurrently across available CPU cores for faster overall build times. The skill helps engineering teams manage large monorepo projects efficiently with faster builds, reduced CI costs, and consistent task orchestration across all workspace packages.

Who Should Use This

This skill serves engineering teams managing multi-package JavaScript monorepos, platform engineers optimizing CI build times, and developers maintaining shared component and utility libraries.

Why Use It?

Problems It Solves

Monorepo builds become increasingly slow when every package rebuilds regardless of changes. Task dependencies between packages require manual ordering that breaks as the repo grows. CI pipelines waste significant time and compute resources rebuilding packages that have not changed since the last successful build run. Local developer builds duplicate work that other team members have already completed.

Core Highlights

Pipeline engine defines explicit task dependencies between packages. Cache system skips unchanged packages using content input hashing. Remote cache shares build artifacts across machines and team developers. Parallel runner executes independent tasks concurrently across cores.

How to Use It?

Basic Usage

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

Real-World Examples

// package.json (root)
{
  "name": "monorepo",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "scripts": {
    "build":
      "turbo run build",
    "test":
      "turbo run test",
    "lint":
      "turbo run lint",
    "dev":
      "turbo run dev"
        + " --filter=web"
  },
  "devDependencies": {
    "turbo": "^2.0.0"
  }
}

// Run filtered builds:
// npx turbo run build
//   --filter=@org/ui...
// npx turbo run test
//   --filter=[HEAD~1]

Advanced Tips

Use filter expressions to run tasks only for changed packages and their dependents in CI. Enable remote caching to share build outputs between CI runs and developer machines. Define task inputs explicitly to improve cache hit rates by excluding files that do not affect build output.

When to Use It?

Use Cases

Manage a monorepo with shared UI components, utility libraries, and multiple web applications. Optimize CI build times by caching unchanged package outputs across pipeline runs. Coordinate build order for packages with internal dependencies in a large workspace.

Related Topics

Monorepos, npm workspaces, build systems, CI optimization, remote caching, task orchestration, and package management.

Important Notes

Requirements

Node.js with npm, yarn, or pnpm workspace configuration for defining monorepo package boundaries. Turbo CLI installed as a dev dependency with turbo.json configuration defining task pipelines and output directories. Remote cache provider such as Vercel or self-hosted solutions for sharing build artifacts across team environments and CI pipelines to maximize cache hit rates.

Usage Recommendations

Do: define outputs explicitly for each task to ensure correct caching behavior. Use the caret dependsOn syntax to express cross-package build dependencies. Run only affected packages in CI using filter flags for faster pipeline execution.

Don't: cache tasks with side effects like deployment scripts that should always execute. Rely solely on local cache when team members need to share build artifacts. Ignore workspace dependency cycles since they cause build ordering failures.

Limitations

Remote caching requires reliable network access and adds latency for uploading and downloading large build artifacts. Cache invalidation relies on input hashing which may miss changes from environment variables, external service states, or system-level dependency updates. Task pipelines cannot express conditional execution logic or dynamic task generation beyond static dependency ordering and package filtering, which limits complex workflow automation.