Turborepo - Quick Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: turborepo for comprehensive documentation.

When NOT to Use This Skill

• Nx monorepos - Use nx skill for Nx-specific features

• Single package projects - No need for monorepo tools

• Need advanced generators - Nx has better code generation

• Complex module boundaries - Nx enforces them better

When to Use This Skill

• Monorepo with multiple packages

• Build caching and optimization

• CI/CD for monorepos

• Complex task orchestration

Setup

New monorepo

npx create-turbo@latest my-monorepo

Add to existing monorepo

npm install turbo --save-dev

Project Structure

my-monorepo/ ├── turbo.json ├── package.json ├── apps/ │ ├── web/ │ │ └── package.json │ └── api/ │ └── package.json └── packages/ ├── ui/ │ └── package.json ├── config/ │ └── package.json └── utils/ └── package.json

Configuration (turbo.json)

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

Task Configuration

{ "tasks": { "build": { // Run dependencies' build first "dependsOn": ["^build"],

  // Files that affect cache
  "inputs": [
    "src/**",
    "package.json",
    "tsconfig.json"
  ],

  // Outputs to cache
  "outputs": ["dist/**"],

  // Environment variables that affect cache
  "env": ["NODE_ENV", "API_URL"],

  // Pass-through env vars (not cached)
  "passThroughEnv": ["CI", "GITHUB_TOKEN"]
},

"dev": {
  // Don't cache dev tasks
  "cache": false,

  // Keep running (watch mode)
  "persistent": true
},

"deploy": {
  // Run after build
  "dependsOn": ["build"],

  // No outputs
  "outputs": []
}

} }

Running Tasks

Run task in all packages

turbo build turbo lint turbo test

Run in specific package

turbo build --filter=@myorg/web turbo build --filter=web

Run in multiple packages

turbo build --filter=@myorg/web --filter=@myorg/api

Run with dependencies

turbo build --filter=@myorg/web... # web + its dependencies turbo build --filter=...@myorg/ui # ui + its dependents

Since git ref

turbo build --filter=[HEAD^1] # Changed since last commit turbo build --filter=[origin/main] # Changed since main

Parallel execution

turbo dev

Dry run

turbo build --dry-run turbo build --graph # Output dependency graph

Package Configuration

// apps/web/package.json { "name": "@myorg/web", "scripts": { "build": "next build", "dev": "next dev", "lint": "eslint .", "test": "vitest run" }, "dependencies": { "@myorg/ui": "", "@myorg/utils": "" } }

// packages/ui/package.json { "name": "@myorg/ui", "scripts": { "build": "tsup src/index.ts --dts", "dev": "tsup src/index.ts --watch", "lint": "eslint ." } }

Root package.json

{ "name": "my-monorepo", "private": true, "workspaces": ["apps/", "packages/"], "scripts": { "build": "turbo build", "dev": "turbo dev", "lint": "turbo lint", "test": "turbo test", "typecheck": "turbo typecheck", "clean": "turbo clean && rm -rf node_modules" }, "devDependencies": { "turbo": "^2.0.0" } }

Caching

Local Cache

Cache stored in node_modules/.cache/turbo

Force fresh build

turbo build --force

View cache status

turbo build --summarize

Remote Cache (Vercel)

Login to Vercel

turbo login

Link to remote cache

turbo link

Now builds use remote cache

turbo build

Self-hosted Remote Cache

// turbo.json { "remoteCache": { "enabled": true, "signature": true } }

Use custom remote cache

TURBO_API="https://your-cache-server.com"
TURBO_TOKEN="your-token"
TURBO_TEAM="your-team"
turbo build

Environment Variables

// turbo.json { "globalEnv": ["CI", "NODE_ENV"], "globalPassThroughEnv": ["GITHUB_TOKEN"], "tasks": { "build": { "env": ["API_URL", "DATABASE_URL"], "passThroughEnv": ["VERCEL_URL"] } } }

.env Files

// turbo.json { "globalDotEnv": [".env"], "tasks": { "build": { "dotEnv": [".env.production", ".env.local"] } } }

CI/CD

GitHub Actions

name: CI

on: push: branches: [main] pull_request:

jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 2 # Needed for --filter=[HEAD^1]

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

  - name: Install
    run: npm ci

  - name: Build
    run: npx turbo build --filter=[HEAD^1]

  - name: Test
    run: npx turbo test --filter=[HEAD^1]

  - name: Lint
    run: npx turbo lint --filter=[HEAD^1]

With Remote Cache

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

Package-specific Config

// apps/web/turbo.json { "extends": ["//"], "tasks": { "build": { "outputs": [".next/", "!.next/cache/"] } } }

Generators

Create generator

turbo gen init

Run generator

turbo gen workspace

// turbo/generators/config.ts import { PlopTypes } from "@turbo/gen";

export default function generator(plop: PlopTypes.NodePlopAPI): void { plop.setGenerator("package", { description: "Create a new package", prompts: [ { type: "input", name: "name", message: "Package name?", }, ], actions: [ { type: "add", path: "packages/{{name}}/package.json", templateFile: "templates/package.json.hbs", }, ], }); }

Task Dependencies

{ "tasks": { // topological: run in dependencies first "build": { "dependsOn": ["^build"] },

// same package: run after
"test": {
  "dependsOn": ["build"]
},

// specific package
"deploy": {
  "dependsOn": ["@myorg/web#build", "@myorg/api#build"]
},

// no dependencies
"lint": {
  "dependsOn": []
}

} }

Debugging

Verbose output

turbo build --verbosity=2

Dry run

turbo build --dry-run=json

Graph visualization

turbo build --graph=graph.html

Summarize

turbo build --summarize

Profile

turbo build --profile=profile.json

Comparison: Turborepo vs Nx

Feature Turborepo Nx

Setup Simple Complex

Config JSON TypeScript

Caching Excellent Excellent

Task runner Fast Fast

Generators Basic Advanced

Plugins Limited Extensive

Learning curve Low Medium

Vercel integration Native Manual

When to Use

Scenario Recommendation

Simple monorepo Turborepo

Complex enterprise Nx

Vercel deployment Turborepo

Need generators Nx

Quick setup Turborepo

Anti-Patterns to Avoid

• Do not forget --filter for incremental builds

• Do not cache tasks with side effects

• Do not ignore outputs configuration

• Do not use * in workspace dependencies (use workspace protocol)

Anti-Patterns

Anti-Pattern Why It's Bad Correct Approach

Not using --filter Rebuilds everything Use --filter for affected packages

Caching side effects Unreliable deployments Set cache: false for deploy tasks

Missing outputs Cache doesn't work Declare all output directories

Using * for workspace deps Version conflicts Use workspace:* protocol

No remote cache in CI Slow CI builds Setup Vercel or self-hosted cache

Forgetting env in turbo.json Cache misses Declare env vars that affect output

Quick Troubleshooting

Issue Cause Solution

Cache always misses Missing outputs Add outputs to turbo.json task

Task runs when shouldn't Wrong dependsOn Check ^build syntax for dependencies

Slow builds Not using cache Enable remote cache or check outputs

Wrong execution order Missing dependsOn Add dependsOn: ["^build"]

Env vars not working Not declared Add to env or passThroughEnv

Remote cache not working Auth issue Check TURBO_TOKEN and TURBO_TEAM

Checklist

• turbo.json with task definitions

• ^build for topological dependencies

• outputs configured for caching

• env vars declared

• Remote cache for CI

• --filter for incremental builds

Further Reading

For advanced configurations: mcp__documentation__fetch_docs

• Technology: turborepo

• Turborepo Docs