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