Turborepo Monorepo

Overview

When to Use

• Creating a new Turborepo workspace or initializing in an existing project
• Configuring

  turbo.json

  tasks with proper dependencies and outputs
• Setting up Next.js or NestJS applications in a monorepo
• Configuring Vitest or Jest testing pipelines
• Implementing CI/CD workflows (GitHub Actions, CircleCI, GitLab CI)
• Setting up remote caching or Vercel Remote Cache
• Optimizing build times and cache hit ratios
• Managing package configurations for specific apps/libs
• Debugging task dependency issues
• Migrating from other monorepo tools to Turborepo

Instructions

Workspace Creation

1. Create a new workspace:
   bash

   # Using pnpm (recommended)
   pnpm create turbo@latest my-workspace
   
   # Using npm
   npm create turbo@latest my-workspace
   
   # Using yarn
   yarn create turbo my-workspace

2. Initialize in an existing project:
   bash

   pnpm add -D -w turbo

3. Create turbo.json in root:
   json

   {
     "$schema": "https://turborepo.dev/schema.json",
     "pipeline": {
       "build": {
         "dependsOn": ["^build"],
         "outputs": ["dist/**", ".next/**"]
       },
       "lint": {
         "outputs": []
       },
       "test": {
         "dependsOn": ["build"],
         "outputs": ["coverage/**"]
       }
     }
   }

4. Add scripts to root package.json:
   json

   {
     "scripts": {
       "build": "turbo run build",
       "dev": "turbo run dev",
       "lint": "turbo run lint",
       "test": "turbo run test",
       "clean": "turbo run clean"
     }
   }

Task Configuration

1. Configure task dependencies:
   json

   {
     "pipeline": {
       "build": {
         "dependsOn": ["^build"],
         "outputs": ["dist/**"]
       },
       "test": {
         "dependsOn": ["build"],
         "outputs": ["coverage/**"]
       },
       "lint": {
         "outputs": []
       }
     }
   }

2. Run tasks across packages:
   bash

   # Run task for all packages
   turbo run build
   
   # Run multiple tasks
   turbo run lint test build
   
   # Run for specific package
   turbo run build --filter=web

3. Use transit nodes for parallel type checking:
   json

   {
     "pipeline": {
       "transit": {
         "dependsOn": ["^transit"]
       },
       "typecheck": {
         "dependsOn": ["transit"],
         "outputs": []
       }
     }
   }

Framework Integration

1. Next.js app configuration:
   json

   {
     "pipeline": {
       "build": {
         "dependsOn": ["^build"],
         "outputs": [".next/**", "!.next/cache/**"],
         "env": ["NEXT_PUBLIC_*"]
       }
     }
   }

   See references/nextjs-config.md for complete Next.js setup.
2. NestJS API configuration:
   json

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

   See references/nestjs-config.md for complete NestJS setup.

Testing Setup

1. Vitest configuration:
   json

   {
     "pipeline": {
       "test": {
         "outputs": [],
         "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
       },
       "test:watch": {
         "cache": false,
         "persistent": true
       }
     }
   }

2. Run affected tests:
   bash

   turbo run test --filter=[HEAD^]

   See references/testing-config.md for complete testing setup.

Package Configurations

1. Create package-specific turbo.json:
   json

   {
     "extends": ["//"],
     "tasks": {
       "build": {
         "outputs": ["$TURBO_EXTENDS$", ".next/**"]
       }
     }
   }

   See references/package-configs.md for detailed package configuration patterns.

CI/CD Setup

1. GitHub Actions basic workflow:
   yaml

   - name: Install dependencies
     run: pnpm install
   
   - name: Run tests
     run: pnpm run test --filter=[HEAD^]
   
   - name: Build
     run: pnpm run build --filter=[HEAD^]

2. Remote cache setup:
   bash

   # Login to Vercel
   npx turbo login
   
   # Link repository
   npx turbo link

   See references/ci-cd.md for complete CI/CD setup examples.

Task Properties Reference

dependsOn

["^build"]

outputs

["dist/**"]

inputs

["src/**/*.ts"]

env

["DATABASE_URL"]

cache

true

false

persistent

true

outputLogs

"full"

"new-only"

"errors-only"

Dependency Patterns

• ^task

  - Run task in dependencies first (topological order)

• task

  - Run task in same package first

• package#task

  - Run specific package's task

Filter Syntax

web

web...

...web

...web...

[HEAD^]

./apps/*

Best Practices

Performance Optimization

1. Use specific outputs - Only cache what's needed
2. Fine-tune inputs - Exclude files that don't affect output
3. Transit nodes - Enable parallel type checking
4. Remote cache - Share cache across team/CI
5. Package configurations - Customize per-package behavior

Caching Strategy

{
  "pipeline": {
    "build": {
      "outputs": ["dist/**"],
      "inputs": ["$TURBO_DEFAULT$", "!README.md", "!**/*.md"]
    }
  }
}

Task Organization

• Independent tasks - No

  dependsOn

  : lint, format, spellcheck
• Build tasks -

  dependsOn: ["^build"]

  : build, compile
• Test tasks -

  dependsOn: ["build"]

  : test, e2e
• Dev tasks -

  cache: false, persistent: true

  : dev, watch

Workspace Structure

my-workspace/
├── apps/
│   ├── web/           # Next.js app
│   └── api/           # NestJS backend
├── packages/
│   ├── ui/            # React component library
│   └── config/        # Shared configs
├── turbo.json
├── package.json
└── pnpm-workspace.yaml

Common Issues

Tasks not running in order

dependsOn

{
  "build": {
    "dependsOn": ["^build"]
  }
}

Cache misses on unchanged files

globalDependencies

inputs

{
  "globalDependencies": ["tsconfig.json"],
  "pipeline": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "!*.md"]
    }
  }
}

Type errors after cache hit

{
  "transit": { "dependsOn": ["^transit"] },
  "typecheck": { "dependsOn": ["transit"] }
}

Examples

Example 1: Create New Workspace

pnpm create turbo@latest my-workspace
cd my-workspace

# Add Next.js app
pnpm add next react react-dom -F apps/web

# Add NestJS API
pnpm add @nestjs/core @nestjs/common -F apps/api

Example 2: Configure Testing Pipeline

{
  "pipeline": {
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
    },
    "test:watch": {
      "cache": false,
      "persistent": true
    }
  }
}

Example 3: Run Affected Tests in CI

pnpm run test --filter=[HEAD^]

Example 4: Debug Cache Issues

# Dry run to see what would be executed
turbo run build --dry-run --filter=web

# Show hash inputs
turbo run build --force --filter=web

Constraints and Warnings

• Node.js 18+ is required for Turborepo
• Package manager field required in root

  package.json

• Outputs must be specified for caching to work
• Persistent tasks cannot have dependents
• Windows: WSL or Git Bash recommended
• Remote cache requires Vercel account or self-hosted solution
• Large monorepos may need increased

  concurrency

  settings

Reference Files