turborepo

{
  "$schema": "https://turborepo.dev/schema.json",
  "globalDependencies": [".env"],
  "globalEnv": ["CI", "NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"],
      "env": ["DATABASE_URL", "NEXT_PUBLIC_API_URL"],
      "inputs": ["src/**", "package.json", "tsconfig.json"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "env": ["TEST_DATABASE_URL"]
    },
    "test:unit": {
      "dependsOn": [],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "inputs": ["src/**", ".eslintrc.*"]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsconfig.json"]
    },
    "db:generate": {
      "cache": false
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

# Single package
turbo build --filter=web
 
# Package and its dependencies
turbo build --filter=web...
 
# Package and its dependents (what depends on it)
turbo build --filter=...ui
 
# Multiple packages
turbo build --filter=web --filter=api
 
# By directory
turbo build --filter=./apps/*
 
# Packages that changed since main
turbo build --filter=[main]
 
# Combine: changed packages and their dependents
turbo build --filter=...[main]
 
# Exclude a package
turbo build --filter=!docs
 
# Packages matching a pattern
turbo build --filter=@myorg/*

name: CI
on: [push, pull_request]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Required for --affected
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: turbo build test lint --affected
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
 
  deploy-web:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: turbo build --filter=web
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.list.outputs.packages }}
    steps:
      - uses: actions/checkout@v4
      - id: list
        run: |
          PACKAGES=$(turbo ls --affected --output=json | jq -c '[.[].name]')
          echo "packages=$PACKAGES" >> "$GITHUB_OUTPUT"
 
  test:
    needs: detect
    if: needs.detect.outputs.packages != '[]'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: ${{ fromJson(needs.detect.outputs.packages) }}
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: turbo test --filter=${{ matrix.package }}

# Set in CI environment
TURBO_TOKEN=your-vercel-token
TURBO_TEAM=your-vercel-team
 
# Builds automatically use remote cache
turbo build

# Watch a specific task
turbo watch test
 
# Watch with a filter
turbo watch test --filter=web
 
# Watch multiple tasks
turbo watch test lint

{
  "boundaries": {
    "tags": {
      "apps/*": ["app"],
      "packages/ui": ["shared", "ui"],
      "packages/utils": ["shared"],
      "packages/config": ["config"]
    },
    "rules": [
      {
        "from": ["app"],
        "allow": ["shared"]
      },
      {
        "from": ["shared"],
        "deny": ["app"]
      }
    ]
  }
}

# Check boundary compliance
turbo boundaries
 
# Add to your pipeline
{
  "tasks": {
    "check": {
      "dependsOn": ["lint", "typecheck", "boundaries"]
    },
    "boundaries": {}
  }
}

# Print graph to terminal
turbo build --graph
 
# Output as DOT format (Graphviz)
turbo build --graph=graph.dot
 
# Output as JSON
turbo build --graph=graph.json
 
# Open interactive graph in browser
turbo build --graph=graph.html

# Show tasks that would run without executing them
turbo build --dry-run
 
# JSON output for programmatic use
turbo build --dry-run=json

# Visual package/task graph explorer (hot-reloads on changes)
turbo devtools
 
# Search Turborepo docs from the terminal (returns agent-friendly markdown)
turbo docs
 
# Upgrade to latest Turborepo
npx @turbo/codemod migrate

// packages/ui/turbo.json
{
  "extends": ["@myorg/config"],
  "tasks": {
    "build": {
      "outputs": ["dist/**"]
    }
  }
}

# Run build across all packages
turbo build
 
# Run only affected packages (changed since main branch)
turbo build --affected
 
# Run specific tasks in specific packages
turbo build --filter=web
 
# Run with remote caching
turbo build --remote-cache
 
# Prune monorepo for a single app deployment
turbo prune web --docker
 
# List all packages
turbo ls
 
# List affected packages
turbo ls --affected

# Login to Vercel for remote caching
turbo login
 
# Link to a Vercel team
turbo link
 
# Now builds share cache across all machines
turbo build  # Cache hits from CI, teammates, etc.

my-monorepo/
├── turbo.json
├── package.json
├── apps/
│   ├── web/           # Next.js app
│   │   └── package.json
│   ├── api/           # Backend service
│   │   └── package.json
│   └── docs/          # Documentation site
│       └── package.json
├── packages/
│   ├── ui/            # Shared component library
│   │   └── package.json
│   ├── config/        # Shared configs (eslint, tsconfig)
│   │   └── package.json
│   └── utils/         # Shared utilities
│       └── package.json
└── node_modules/

# Only build/test packages that changed since main
turbo build test lint --affected

my-platform/
├── turbo.json
├── package.json
├── apps/
│   ├── shell/          # Layout / shell app (owns top-level routing)
│   ├── dashboard/      # Micro-app: dashboard features
│   ├── settings/       # Micro-app: settings features
│   └── marketing/      # Micro-app: public marketing site
└── packages/
    ├── ui/             # Shared component library
    ├── auth/           # Shared auth utilities
    └── config/         # Shared tsconfig, eslint

# Deploy only the dashboard micro-app
turbo build --filter=dashboard
 
# Deploy all micro-apps in parallel
turbo build --filter=./apps/*
 
# Deploy only micro-apps that changed since main
turbo build --filter=./apps/*...[main]

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    }
  }
}

// apps/shell/next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  async rewrites() {
    return [
      { source: '/dashboard/:path*', destination: 'https://dashboard.example.com/dashboard/:path*' },
      { source: '/settings/:path*', destination: 'https://settings.example.com/settings/:path*' },
    ]
  },
}
 
export default nextConfig

{
  "boundaries": {
    "tags": {
      "apps/*": ["micro-app"],
      "packages/ui": ["shared"],
      "packages/auth": ["shared"]
    },
    "rules": [
      { "from": ["micro-app"], "allow": ["shared"] },
      { "from": ["shared"], "deny": ["micro-app"] }
    ]
  }
}

# Ensure text lockfile for Turborepo compatibility
bun install --save-text-lockfile
 
# Run only affected packages (works with Bun lockfile detection)
turbo build --affected