Turborepo Monorepo

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:

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

2. Initialize in existing project:

   pnpm add -D -w turbo

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

   {
     "$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:

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

5. Validate task graph before CI:

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

Task Configuration

1. Configure tasks in turbo.json:

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

2. Run tasks:

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

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

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

4. Validate before committing:

   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:

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

2. Run affected tests:

   turbo run test --filter=[HEAD^]

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

Package Configurations

1. Create package-specific turbo.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:

   - 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

2. Remote cache setup:

   # 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