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

-

Create a new workspace:

pnpm create turbo@latest my-workspace

cd my-workspace

-

Initialize in existing project:

pnpm add -D -w turbo

-

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/**"] }

  }

}

-

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

-

Validate task graph before CI:

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

Task Configuration

-

Configure tasks in turbo.json:

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

-

Run tasks:

turbo run build                      # All packages

turbo run lint test build           # Multiple tasks

turbo run build --filter=web       # Specific package

-

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

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

-

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

-

Vitest configuration:

{

  "pipeline": {

    "test": {

      "outputs": [],

      "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]

    },

    "test:watch": {

      "cache": false,

      "persistent": true

    }

  }

}

-

Run affected tests:

turbo run test --filter=[HEAD^]

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

Package Configurations

• 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

-

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

-

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

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

• Use specific outputs - Only cache what's needed

• Fine-tune inputs - Exclude files that don't affect output

• Transit nodes - Enable parallel type checking

• Remote cache - Share cache across team/CI

• 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

Common Issues

Tasks not running in order

Problem: Tasks execute in wrong order

Solution: Check dependsOn configuration

{

  "build": {

    "dependsOn": ["^build"]

  }

}

Cache misses on unchanged files

Problem: Cache invalidating unexpectedly

Solution: Review globalDependencies and inputs

{

  "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

{

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

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

}

Examples

Example 1: Create New Workspace

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

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"

{

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

pnpm run test --filter=[HEAD^]

Example 4: Debug Cache Issues

Input: "Why is my cache missing?"

# 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