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:** ```bash pnpm create turbo@latest my-workspace cd my-workspace ``` 2. **Initialize in existing project:** ```bash pnpm add -D -w turbo ``` 3. **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/**"] } } } ``` 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" } } ``` 5. **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": [] } } } ``` 2. **Run tasks:** ```bash 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): ```json { "pipeline": { "transit": { "dependsOn": ["^transit"] }, "typecheck": { "dependsOn": ["transit"] } } } ``` 4. **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](references/nextjs-config.md) **NestJS:** outputs `"dist/**"`, dev tasks with `cache: false, persistent: true` - See [references/nestjs-config.md](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 } } } ``` 2. **Run affected tests:** ```bash turbo run test --filter=[HEAD^] ``` See [references/testing-config.md](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](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 ``` 2. **Remote cache setup:** ```bash # Login to Vercel npx turbo login # Link repository npx turbo link ``` See [references/ci-cd.md](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](references/turbo.json) | | Next.js integration | [references/nextjs-config.md](references/nextjs-config.md) | | NestJS integration | [references/nestjs-config.md](references/nestjs-config.md) | | Vitest/Jest/Playwright | [references/testing-config.md](references/testing-config.md) | | GitHub/CircleCI/GitLab CI | [references/ci-cd.md](references/ci-cd.md) | | Package configurations | [references/package-configs.md](references/package-configs.md) |