Turborepo Monorepo

Overview

Provides guidance for Turborepo monorepo management: workspace creation, turbo.json task configuration, Next.js/NestJS integration, testing pipelines (Vitest/Jest), CI/CD setup, and build performance optimization.

When to Use

• Create or initialize Turborepo workspaces
• Configure turbo.json tasks with dependencies and outputs
• Set up Next.js/NestJS apps in monorepo structure
• Configure Vitest/Jest test pipelines
• Build CI/CD workflows (GitHub Actions, GitLab CI)
• Implement remote caching with Vercel Remote Cache
• Optimize build times and cache hit ratios
• Debug task dependency or cache issues
• Migrate from other monorepo tools to Turborepo

Instructions

Workspace Creation

1. Create a new workspace:

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

1. Initialize in existing project:

bash pnpm add -D -w turbo

1. Create turbo.json in root (minimal config):

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

1. 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" } }

1. Validate task graph before CI:

bash turbo run build --dry-run --filter=... # Verify task execution order

Task Configuration

1. Configure tasks in turbo.json:

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

1. Run tasks:

bash turbo run build # All packages turbo run lint test build # Multiple tasks turbo run build --filter=web # Specific package

1. Parallel type checking (use transit nodes to avoid cache issues):

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

1. Validate before committing:

bash turbo run build --dry-run # Check task order and affected packages

Framework Integration

Next.js: outputs ".next/**" and env ["NEXT_PUBLIC_*"] - See references/nextjs-config.md

NestJS: outputs "dist/**", dev tasks with cache: false, persistent: true - See references/nestjs-config.md

Testing Setup

1. Vitest configuration:

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

1. 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 with validation checkpoints:

yaml

• name: Install dependencies

run: pnpm install

• name: Validate affected packages (dry-run)

run: pnpm turbo run build --filter=HEAD^] --dry-run # VALIDATE: Review output to confirm only expected packages will build

• name: Run tests

run: pnpm run test --filter=HEAD^]

• name: Build affected packages

run: pnpm run build --filter=HEAD^]

• name: Verify cache hits

run: pnpm turbo run build --filter=HEAD^] --dry-run | grep "Cache" # VALIDATE: Confirm cache hits for unchanged packages

1. 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

| Property | Description | Example | |----------|-------------|---------| | dependsOn | Tasks that must complete first | ["^build"] - dependencies first | | outputs | Files/folders to cache | ["dist/**"] | | inputs | Files for cache hash | ["src/**/*.ts"] | | env | Environment variables affecting hash | ["DATABASE_URL"] | | cache | Enable/disable caching | true or false | | persistent | Long-running task | true for dev servers | | outputLogs | Log verbosity | "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

| Filter | Description | |--------|-------------| | web | Only web package | | web... | web + all dependencies | | ...web | web + all dependents | | ...web... | web + deps + dependents | | [HEAD^] | Packages changed since last commit | | ./apps/* | All packages in 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

json
{
  "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

Common Issues

Tasks not running in order

Problem: Tasks execute in wrong order

Solution: Check dependsOn configuration

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

Cache misses on unchanged files

Problem: Cache invalidating unexpectedly

Solution: Review globalDependencies and inputs

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

Type errors after cache hit

Problem: TypeScript errors not caught due to cache

Solution: Use transit nodes for type checking

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

Examples

Example 1: Create New Workspace

Input: "Create a Turborepo with Next.js and NestJS"

bash
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

Input: "Set up Vitest for all packages"

json
{
  "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

Input: "Only test changed packages in CI"

bash
pnpm run test --filter=[HEAD^]

Example 4: Debug Cache Issues

Input: "Why is my cache missing?"

bash
# 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

For detailed guidance on specific topics, consult:

| Topic | Reference File | |-------|----------------| | turbo.json template | references/turbo.json | | Next.js integration | references/nextjs-config.md | | NestJS integration | references/nestjs-config.md | | Vitest/Jest/Playwright | references/testing-config.md | | GitHub/CircleCI/GitLab CI | references/ci-cd.md | | Package configurations | references/package-configs.md |