Turborepo

Turborepo Skill

Turborepo is a high-performance build system optimized for JavaScript and TypeScript monorepos, written in Rust. It provides intelligent caching, task orchestration, and remote execution capabilities to dramatically speed up development workflows.

Reference

https://turborepo.com/llms.txt

When to Use This Skill

Use this skill when:

• Setting up a new monorepo with multiple packages
• Optimizing build performance in existing monorepos
• Implementing task pipelines across packages
• Configuring intelligent caching strategies
• Setting up remote caching for teams
• Orchestrating tasks with dependency awareness
• Integrating monorepo with CI/CD pipelines
• Migrating from Lerna, Nx, or other monorepo tools
• Building microfrontends or shared libraries
• Managing workspace dependencies

Core Concepts

1. Monorepo Architecture

Turborepo organizes code into packages within a single repository:

• Root Package: Contains workspace configuration
• Internal Packages: Shared libraries, utilities, configs
• Applications: Frontend apps, backend services, etc.
• Workspaces: npm/yarn/pnpm workspace configuration

2. Task Pipeline

Tasks are organized in a dependency graph:

• Task Dependencies: Define execution order (build before test)
• Package Dependencies: Respect internal package relationships
• Parallel Execution: Run independent tasks simultaneously
• Topological Ordering: Execute tasks in correct dependency order

3. Intelligent Caching

Turborepo caches task outputs based on inputs:

• Local Cache: Stores outputs on local machine
• Remote Cache: Shares cache across team/CI (Vercel or custom)
• Content-Based Hashing: Only re-run when inputs change
• Cache Restoration: Instant task completion from cache

4. Task Outputs

Define what gets cached:

• Build artifacts (dist/, build/)
• Test results
• Generated files
• Type definitions

Installation

Prerequisites

bashCopy code
# Requires Node.js 18+ and a package manager
node --version  # v18.0.0+

Global Installation

bashCopy code
# npm
npm install turbo --global

# yarn
yarn global add turbo

# pnpm
pnpm add turbo --global

# bun
bun add turbo --global

Per-Project Installation

bashCopy code
# npm
npm install turbo --save-dev

# yarn
yarn add turbo --dev

# pnpm
pnpm add turbo --save-dev

# bun
bun add turbo --dev

Project Setup

Create New Monorepo

Using official examples:

bashCopy code
npx create-turbo@latest

Interactive prompts will ask:

• Project name
• Package manager (npm/yarn/pnpm/bun)
• Example template selection

Manual Setup

1. Initialize workspace:

jsonCopy code
// package.json (root)
{
  "name": "my-turborepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint"
  },
  "devDependencies": {
    "turbo": "latest"
  }
}

2. Create directory structure:

Copy code
my-turborepo/
├── apps/
│   ├── web/              # Next.js app
│   └── docs/             # Documentation site
├── packages/
│   ├── ui/               # Shared UI components
│   ├── config/           # Shared configs (ESLint, TS)
│   └── tsconfig/         # Shared TypeScript configs
├── turbo.json            # Turborepo configuration
└── package.json          # Root package.json

3. Create turbo.json:

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

Configuration (turbo.json)

Basic Structure

jsonCopy code
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env", "tsconfig.json"],
  "globalEnv": ["NODE_ENV"],
  "pipeline": {
    // Task definitions
  }
}

Pipeline Configuration

Task with dependencies:

jsonCopy code
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"],
      "env": ["NODE_ENV", "API_URL"]
    }
  }
}

Key properties:

• dependsOn: Tasks to run first
  • ["^build"]: Run dependencies' build first
  • ["build"]: Run own build first
  • ["^build", "lint"]: Run deps' build and own lint
• outputs: Files/directories to cache
• inputs: Override input detection (default: all tracked files)
• cache: Enable/disable caching (default: true)
• env: Environment variables that affect output
• persistent: Keep task running (for dev servers)
• outputMode: Control output display

Task Dependency Patterns

Topological (^):

jsonCopy code
{
  "build": {
    "dependsOn": ["^build"]  // Run dependencies' build first
  }
}

Regular:

jsonCopy code
{
  "deploy": {
    "dependsOn": ["build", "test"]  // Run own build and test first
  }
}

Combined:

jsonCopy code
{
  "test": {
    "dependsOn": ["^build", "lint"]  // Deps' build, then own lint
  }
}

Output Modes

jsonCopy code
{
  "pipeline": {
    "build": {
      "outputMode": "full"        // Show all output
    },
    "dev": {
      "outputMode": "hash-only"   // Show cache hash only
    },
    "test": {
      "outputMode": "new-only"    // Show new output only
    },
    "lint": {
      "outputMode": "errors-only" // Show errors only
    }
  }
}

Environment Variables

Global environment variables:

jsonCopy code
{
  "globalEnv": ["NODE_ENV", "CI"],
  "globalDependencies": [".env", ".env.local"]
}

Per-task environment variables:

jsonCopy code
{
  "pipeline": {
    "build": {
      "env": ["NEXT_PUBLIC_API_URL", "DATABASE_URL"],
      "passThroughEnv": ["CUSTOM_VAR"]  // Pass without hashing
    }
  }
}

Commands

turbo run

Run tasks across packages:

bashCopy code
# Run build in all packages
turbo run build

# Run multiple tasks
turbo run build test lint

# Run in specific packages
turbo run build --filter=web
turbo run build --filter=@myorg/ui

# Run in packages matching pattern
turbo run build --filter='./apps/*'

# Force execution (skip cache)
turbo run build --force

# Run from specific directory
turbo run build --filter='[./apps/web]'

# Run with dependencies
turbo run build --filter='...^web'

# Parallel execution control
turbo run build --concurrency=3
turbo run build --concurrency=50%

# Continue on error
turbo run test --continue

# Dry run
turbo run build --dry-run

# Output control
turbo run build --output-logs=new-only
turbo run build --output-logs=hash-only
turbo run build --output-logs=errors-only
turbo run build --output-logs=full

turbo prune

Create a subset of the monorepo:

bashCopy code
# Prune for specific app
turbo prune --scope=web

# Prune with Docker
turbo prune --scope=api --docker

# Output to custom directory
turbo prune --scope=web --out-dir=./deploy

Use cases:

• Docker builds (only include necessary packages)
• Deploy specific apps
• Reduce CI/CD context size

turbo gen

Generate code in your monorepo:

bashCopy code
# Generate new package
turbo gen workspace

# Generate from custom generator
turbo gen my-generator

# List available generators
turbo gen --list

turbo link

Link local repo to remote cache:

bashCopy code
# Link to Vercel
turbo link

# Unlink
turbo unlink

turbo login

Authenticate with Vercel:

bashCopy code
turbo login

turbo ls

List packages in monorepo:

bashCopy code
# List all packages
turbo ls

# JSON output
turbo ls --json

Filtering

Filter by Package Name

bashCopy code
# Single package
turbo run build --filter=web

# Multiple packages
turbo run build --filter=web --filter=api

# Scoped package
turbo run build --filter=@myorg/ui

Filter by Pattern

bashCopy code
# All apps
turbo run build --filter='./apps/*'

# Pattern matching
turbo run build --filter='*-ui'

Filter by Directory

bashCopy code
# From specific directory
turbo run build --filter='[./apps/web]'

Filter by Git

bashCopy code
# Changed since main
turbo run build --filter='[main]'

# Changed since HEAD~1
turbo run build --filter='[HEAD~1]'

# Changed in working directory
turbo run test --filter='...[HEAD]'

Filter by Dependencies

bashCopy code
# Package and its dependencies
turbo run build --filter='...web'

# Package's dependencies only
turbo run build --filter='...^web'

# Package and its dependents
turbo run test --filter='ui...'

# Package's dependents only
turbo run test --filter='^ui...'

Caching Strategies

Local Caching

Enabled by default, stores in ./node_modules/.cache/turbo

Cache behavior:

jsonCopy code
{
  "pipeline": {
    "build": {
      "outputs": ["dist/**"],  // Cache dist directory
      "cache": true            // Enable caching (default)
    },
    "dev": {
      "cache": false           // Disable for dev servers
    }
  }
}

Clear cache:

bashCopy code
# Clear Turbo cache
rm -rf ./node_modules/.cache/turbo

# Or use turbo command
turbo run build --force  # Skip cache for this run

Remote Caching

Share cache across team and CI:

1. Link to Vercel (recommended):

bashCopy code
turbo login
turbo link

2. Custom remote cache:

jsonCopy code
// .turbo/config.json
{
  "teamid": "team_123",
  "apiurl": "https://cache.example.com",
  "token": "your-token"
}

Benefits:

• Share builds across team
• Speed up CI/CD
• Consistent builds
• Reduce compute costs

Cache Signatures

Cache is invalidated when:

• Source files change
• Dependencies change
• Environment variables change (if specified)
• Global dependencies change
• Task configuration changes

Control inputs:

jsonCopy code
{
  "pipeline": {
    "build": {
      "inputs": ["src/**/*.ts", "!src/**/*.test.ts"],
      "env": ["NODE_ENV"]
    }
  }
}

Workspace Patterns

Package Types

1. Internal packages (packages/*):

jsonCopy code
// packages/ui/package.json
{
  "name": "@myorg/ui",
  "version": "0.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "lint": "eslint ."
  }
}

2. Applications (apps/*):

jsonCopy code
// apps/web/package.json
{
  "name": "web",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@myorg/ui": "*",
    "next": "latest"
  },
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Dependency Management

Workspace protocol (pnpm/yarn):

jsonCopy code
{
  "dependencies": {
    "@myorg/ui": "workspace:*"
  }
}

Version protocol (npm):

jsonCopy code
{
  "dependencies": {
    "@myorg/ui": "*"
  }
}

Shared Configuration

ESLint config package:

jsCopy code
// packages/eslint-config/index.js
module.exports = {
  extends: ["next", "prettier"],
  rules: {
    // shared rules
  }
}

TypeScript config package:

jsonCopy code
// packages/tsconfig/base.json
{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Usage:

jsonCopy code
// apps/web/tsconfig.json
{
  "extends": "@myorg/tsconfig/base.json",
  "compilerOptions": {
    "jsx": "preserve"
  }
}

CI/CD Integration

GitHub Actions

yamlCopy code
name: CI

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

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npx turbo run build
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

      - name: Test
        run: npx turbo run test

GitLab CI

yamlCopy code
image: node:18

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .turbo/

build:
  stage: build
  script:
    - npm install
    - npx turbo run build
  variables:
    TURBO_TOKEN: $TURBO_TOKEN
    TURBO_TEAM: $TURBO_TEAM

Docker

dockerfileCopy code
FROM node:18-alpine AS base

# Prune workspace
FROM base AS builder
RUN npm install -g turbo
COPY . .
RUN turbo prune --scope=web --docker

# Install dependencies
FROM base AS installer
COPY --from=builder /app/out/json/ .
COPY --from=builder /app/out/package-lock.json ./package-lock.json
RUN npm install

# Build
COPY --from=builder /app/out/full/ .
RUN npx turbo run build --filter=web

# Runner
FROM base AS runner
COPY --from=installer /app/apps/web/.next/standalone ./
COPY --from=installer /app/apps/web/.next/static ./apps/web/.next/static
COPY --from=installer /app/apps/web/public ./apps/web/public

CMD node apps/web/server.js

Optimization Tips

1. Use remote caching in CI:

yamlCopy code
env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

2. Cache node_modules:

yamlCopy code
- uses: actions/cache@v3
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

3. Run only affected tasks:

bashCopy code
turbo run build test --filter='...[origin/main]'

Framework Integration

Next.js

jsonCopy code
// apps/web/package.json
{
  "name": "web",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "latest",
    "react": "latest"
  }
}

turbo.json:

jsonCopy code
{
  "pipeline": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Vite

jsonCopy code
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

NuxtJS

jsonCopy code
{
  "pipeline": {
    "build": {
      "outputs": [".output/**", ".nuxt/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Development Tools Integration

TypeScript

jsonCopy code
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", "*.tsbuildinfo"]
    },
    "typecheck": {
      "dependsOn": ["^build"]
    }
  }
}

ESLint

jsonCopy code
{
  "pipeline": {
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

Jest / Vitest

jsonCopy code
{
  "pipeline": {
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "cache": true
    }
  }
}

Prisma

jsonCopy code
{
  "pipeline": {
    "db:generate": {
      "cache": false
    },
    "db:push": {
      "cache": false
    }
  }
}

Best Practices

1. Structure Your Monorepo

Copy code
my-monorepo/
├── apps/                    # Applications
│   ├── web/                # Frontend app
│   ├── api/                # Backend API
│   └── docs/               # Documentation
├── packages/               # Shared packages
│   ├── ui/                 # UI components
│   ├── config/             # Shared configs
│   ├── utils/              # Utilities
│   └── tsconfig/           # TS configs
├── tooling/                # Development tools
│   ├── eslint-config/
│   └── prettier-config/
└── turbo.json

2. Define Clear Task Dependencies

jsonCopy code
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"]
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "deploy": {
      "dependsOn": ["build", "test", "lint"]
    }
  }
}

3. Optimize Cache Configuration

• Cache build outputs, not source files
• Include all generated files in outputs
• Exclude cache directories (e.g., .next/cache)
• Disable cache for dev servers

jsonCopy code
{
  "pipeline": {
    "build": {
      "outputs": [
        "dist/**",
        ".next/**",
        "!.next/cache/**",
        "storybook-static/**"
      ]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

4. Use Environment Variables Wisely

jsonCopy code
{
  "globalEnv": ["NODE_ENV", "CI"],
  "pipeline": {
    "build": {
      "env": ["NEXT_PUBLIC_API_URL"],
      "passThroughEnv": ["DEBUG"]  // Don't affect cache
    }
  }
}

5. Leverage Remote Caching

• Enable for all team members
• Configure in CI/CD
• Reduces build times significantly
• Especially beneficial for large teams

6. Use Filters Effectively

bashCopy code
# Build only changed packages
turbo run build --filter='...[origin/main]'

# Build specific app with dependencies
turbo run build --filter='...web'

# Test only affected packages
turbo run test --filter='...[HEAD^1]'

7. Organize Scripts Consistently

Root package.json:

jsonCopy code
{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "clean": "turbo run clean && rm -rf node_modules"
  }
}

8. Handle Persistent Tasks

jsonCopy code
{
  "pipeline": {
    "dev": {
      "cache": false,
      "persistent": true  // Keeps running
    }
  }
}

Common Patterns

Full-Stack Application

Copy code
apps/
├── web/          # Next.js frontend
│   └── package.json
├── api/          # Express backend
│   └── package.json
└── mobile/       # React Native
    └── package.json

packages/
├── ui/           # Shared UI components
├── database/     # Database client/migrations
├── types/        # Shared TypeScript types
└── config/       # Shared configs

Shared Component Library

Copy code
packages/
├── ui/                    # Component library
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
└── ui-docs/              # Storybook
    ├── .storybook/
    ├── stories/
    └── package.json

Microfrontends

Copy code
apps/
├── shell/        # Container app
├── dashboard/    # Dashboard MFE
└── settings/     # Settings MFE

packages/
├── shared-ui/    # Shared components
└── router/       # Routing logic

Troubleshooting

Cache Issues

Problem: Task not using cache when it should

bashCopy code
# Check what's causing cache miss
turbo run build --dry-run=json

# Force rebuild
turbo run build --force

# Clear cache
rm -rf ./node_modules/.cache/turbo

Problem: Cache too large

bashCopy code
# Limit cache size in turbo.json
{
  "cacheDir": ".turbo",
  "cacheSize": "50gb"
}

Dependency Issues

Problem: Internal package not found

bashCopy code
# Ensure workspace is set up correctly
npm install

# Check package names match
npm ls @myorg/ui

# Rebuild dependencies
turbo run build --filter='...web'

Task Execution Issues

Problem: Tasks running in wrong order

• Check dependsOn configuration
• Use ^task for dependency tasks
• Verify task names match package.json scripts

Problem: Dev server not starting

jsonCopy code
{
  "pipeline": {
    "dev": {
      "cache": false,
      "persistent": true  // Add this
    }
  }
}

Performance Issues

Problem: Builds taking too long

bashCopy code
# Run with concurrency limit
turbo run build --concurrency=2

# Use filters to build less
turbo run build --filter='...[origin/main]'

# Check for unnecessary dependencies
turbo run build --dry-run

Problem: Remote cache not working

bashCopy code
# Verify authentication
turbo link

# Check environment variables
echo $TURBO_TOKEN
echo $TURBO_TEAM

# Test connection
turbo run build --output-logs=hash-only

Migration Guide

From Lerna

1. Replace Lerna with Turborepo:

bashCopy code
npm uninstall lerna
npm install turbo --save-dev

2. Convert lerna.json to turbo.json:

jsonCopy code
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

3. Update scripts:

jsonCopy code
{
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test"
  }
}

From Nx

1. Install Turborepo:

bashCopy code
npm install turbo --save-dev

2. Convert nx.json to turbo.json:

• Map targetDefaults to pipeline
• Convert dependsOn syntax
• Configure caching

3. Update workspace configuration
4. Migrate CI/CD scripts

Resources

• Documentation: https://turbo.build/repo/docs
• Examples: https://github.com/vercel/turbo/tree/main/examples
• Discord: https://turbo.build/discord
• GitHub: https://github.com/vercel/turbo

Implementation Checklist

When setting up Turborepo:

• Install Turborepo globally or per-project
• Set up workspace structure (apps/, packages/)
• Create turbo.json with pipeline configuration
• Define task dependencies (build, test, lint)
• Configure cache outputs for each task
• Set up global dependencies and environment variables
• Link to remote cache (Vercel or custom)
• Configure CI/CD integration
• Add filtering strategies for large repos
• Document monorepo structure for team
• Set up code generation (turbo gen)
• Configure Docker builds with turbo prune
• Test caching behavior locally
• Verify remote cache in CI
• Optimize concurrency settings