Intermediateturborepoturbomonorepobuild-systemtask-runnercacheverceljavascripttypescriptrust

Turborepo - Monorepo Build System by Vercel

Install and configure Turborepo, the high-performance build system optimized for JavaScript and TypeScript monorepos - covering installation, task orchestration, caching, remote cache, and developer experience.

Step 1
Overview
Turborepo is a high-performance build system designed specifically for JavaScript and TypeScript monorepos, written primarily in Rust. It powers fast builds by intelligently caching and orchestrating task execution across your workspace.

Key capabilities:
- Task Orchestration: Parallel and pipeline-based task execution across monorepo packages
- Local Caching: Automatic caching of task outputs to skip redundant work
- Remote Caching: Cloud-based cache sharing across team members and CI/CD pipelines
- Dependency Graph: Automatically analyzes package dependencies for optimal execution order
- Zero Config Start: Works with existing build tools like Webpack, Vite, Next.js, etc.
Why Turborepo:
- Vercel-backed: Production-ready with massive scale usage
- Rust-powered: Written in Rust for maximum performance
- Developer Experience: Incremental builds, parallel execution, intelligent caching
- CI/CD Integration: Seamless remote cache across machines and environments
- Framework Agnostic: Works with any JavaScript/TypeScript framework or tool
```
Official site: https://turborepo.dev
GitHub: https://github.com/vercel/turborepo (30K+ stars)
Documentation: https://turbo.build/repo/docs
Vercel Product: https://vercel.com/docs/developer-workflow/turborepo
```

Step 2

Installing Turborepo

Install Turborepo globally or as a dev dependency in your project. Using npm is recommended for best results with package managers.

Installation options:

npm global: Install globally for use across projects
npm local: Install as dev dependency in your project
create-turbo: Initialize a new Turborepo monorepo template

# Option 1: Global installation (recommended)
npm install -g turbo

# Verify installation
turbo --version

# Option 2: Local installation (project-specific)
npm install turbo --save-dev

# Use via npx
npx turbo run build

# Option 3: Using with other package managers
yarn global add turbo
pnpm add -D turbo

# Create a new Turborepo monorepo (quick scaffold)
npx create-turbo@latest

# Or with npm/npx
npm init turbo@latest

Step 3

Monorepo Structure

Turborepo works with any monorepo structure. The typical layout has apps and packages at the root level with a configuration file.

Common structure:

apps/: End applications (web apps, APIs, mobile apps)
packages/: Shared libraries and utilities
turbo.json: Turborepo configuration
package.json: Root package manifest with workspaces

# Typical Turborepo structure
my-monorepo/
├── apps/
│   ├── web/                # Next.js frontend
│   │   ├── package.json
│   │   └── src/
│   ├── docs/               # Documentation site
│   │   └── package.json
│   └── api/                # Backend API
│       └── package.json
├── packages/
│   ├── ui/                 # Shared UI component library
│   │   ├── package.json
│   │   └── src/
│   ├── utils/              # Shared utilities
│   │   └── package.json
│   └── types/              # Shared TypeScript types
│       └── package.json
├── turbo.json              # Turborepo config
├── package.json            # Root package with workspaces
├── pnpm-workspace.yaml     # Or your package manager's workspace file
└── node_modules/

Step 4

Basic Configuration

The turbo.json file configures pipelines, remote cache, and global settings. This is the heart of Turborepo configuration.

Key configuration sections:

globalDependencies: Files that invalidate all tasks when changed
pipeline: Task definitions with dependencies and outputs
remoteCache: Configuration for cloud-based caching

{
  "globalDependencies": [".env"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "dev": {
      "cache": false
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    }
  },
  "remoteCache": {
    "authorization": "BASIC_AUTH_TOKEN"
  }
}

Step 5

Running Tasks

Turborepo executes tasks across your monorepo with intelligent caching and parallelization.

Basic commands:

turbo run <task>: Run a task across all packages
turbo <task>: Shorthand when turbo.json exists
--filter: Target specific packages
--concurrency: Control parallel execution

# Run a single task across all packages
turbo run build

# Shorthand (when turbo.json exists)
turbo build

# Run multiple tasks (pipeline style)
turbo build lint

# Run task with filter (specific package)
turbo run build --filter=ui

# Run with glob pattern filter
turbo run build --filter="apps/*"

# Exclude specific packages
turbo run build --filter=".!docs"

# Run with specific concurrency
turbo run build --concurrency=4

# Run with forced execution (skip cache)
turbo run build --force

Step 6
Task Dependencies and Ordering
Turborepo automatically builds a dependency graph to execute tasks in the correct order. Understanding dependency syntax ensures proper pipeline execution.

Dependency types:
- Upstream (^task): Dependencies on the same task in upstream packages
- Downstream (task): Dependencies on the same task in downstream packages
- Cross-task (task2): Dependencies on other tasks in the same package
```
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "lint": {
      "dependsOn": ["^build", "build"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}
```
Step 7
Caching Behavior
Turborepo automatically caches task outputs based on content hashing. Changes to inputs invalidate the cache for dependent tasks.

Caching features:
- Content hashing: Cache keyed by file content, not timestamps
- Output tracking: Specify which outputs to cache
- Cache invalidation: Automatic on dependency changes
- Remote cache: Share cache across machines via Vercel
```
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [
        ".next/**",
        "dist/**",
        "build/**",
        "!.next/cache/**"
      ]
    },
    "test": {
      "outputs": ["coverage/**"],
      "dependsOn": ["build"]
    }
  },
  "globalDependencies": [".env", "tsconfig.json"]
}
```

Step 8

Remote Cache Setup

Turborepo Remote Cache allows teams to share build artifacts via Vercel's infrastructure.

Setup requirements:

Vercel account (free tier available)
Authorization token
teamId configuration

# 1. Login to Vercel for Turborepo
turbo login

# 2. Create a remote cache token at:
# https://vercel.com/v2/tr/<team>/turborepo/tokens

# 3. Configure turbo.json
{
  "remoteCache": {
    "teamId": "your-team-id",
    "authorization": "YOUR_TOKEN"
  }
}

# 4. Or use environment variables (recommended for CI)
export TURBO_TOKEN="your-token-here"
export TURBO_TEAM="your-team-id"

# 5. Run with remote cache
turbo run build

Step 9

CI/CD Integration

Integrate Turborepo with CI/CD platforms like GitHub Actions, GitLab CI, and Vercel for optimized builds with remote caching.

CI benefits:

Shared remote cache across all runners
Parallel job execution
Failed build cache preservation

# .github/workflows/ci.yaml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile

      - run: pnpm turbo run build

Step 10
Resources & Next Steps
Documentation:
Community:
- GitHub Discussions
- Vercel Community - Turborepo
Related Tools:
- Rush - Microsoft's monorepo manager
- Nx - Monorepo with build graph awareness
- pnpm - Fast package manager
Next guides:
- Setting up Turborepo with Next.js
- Integrating Turborepo with CI/CD pipelines
- Advanced monorepo patterns with Turborepo
```
Official site: https://turborepo.dev
GitHub: https://github.com/vercel/turborepo
Documentation: https://turbo.build/repo/docs
Examples: https://github.com/vercel/turborepo-examples
```

Overview

Installing Turborepo

Monorepo Structure

Basic Configuration

Running Tasks

Task Dependencies and Ordering

Caching Behavior

Remote Cache Setup

CI/CD Integration

Resources & Next Steps

Feature requests

Discussion