Skip to content

02-workspace-configuration.md

Latest commit

 

History

History
319 lines (261 loc) · 7.32 KB

02-workspace-configuration.md

File metadata and controls

319 lines (261 loc) · 7.32 KB
layout default
title Chapter 2: Workspace Configuration
parent Turborepo Tutorial
nav_order 2

Chapter 2: Workspace Configuration

Welcome to Chapter 2: Workspace Configuration. In this part of Turborepo Tutorial: High-Performance Monorepo Build System, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

Learn how to configure Turborepo workspaces, manage dependencies, and set up your monorepo structure for optimal performance.

Workspace Setup

Basic Configuration

// package.json
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "packageManager": "pnpm@8.6.0",
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint"
  },
  "devDependencies": {
    "turbo": "^1.10.0"
  }
}

Turbo Configuration

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts", "test/**/*.tsx"]
    }
  },
  "globalDependencies": ["tsconfig.json", "jest.config.js"]
}

Dependency Management

Internal Dependencies

// packages/ui/package.json
{
  "name": "@my-monorepo/ui",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": "./dist/index.js",
    "./styles": "./dist/styles.css"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.0",
    "typescript": "^5.0.0"
  }
}

External Dependencies

// apps/web/package.json
{
  "name": "@my-monorepo/web",
  "version": "1.0.0",
  "scripts": {
    "build": "next build",
    "dev": "next dev",
    "start": "next start"
  },
  "dependencies": {
    "@my-monorepo/ui": "workspace:*",
    "next": "^13.4.0",
    "react": "^18.2.0"
  }
}

Task Dependencies

Build Order Management

// turbo.json with dependencies
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**", "test/**"]
    },
    "deploy": {
      "dependsOn": ["build", "test"],
      "outputs": []
    }
  }
}

Pipeline Configuration

// Complex pipeline setup
{
  "tasks": {
    "typecheck": {
      "dependsOn": ["^build"]
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "__tests__/**"]
    },
    "build": {
      "dependsOn": ["typecheck", "lint"],
      "inputs": ["src/**", "package.json"],
      "outputs": ["dist/**"]
    },
    "deploy": {
      "dependsOn": ["build", "test"],
      "env": ["VERCEL_TOKEN"]
    }
  }
}

Caching Strategies

Cache Configuration

// Advanced caching
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": [
        "src/**",
        "public/**",
        "package.json",
        "next.config.js",
        "tailwind.config.js"
      ],
      "outputs": [".next/**", "dist/**", "!.next/cache/**"],
      "env": ["NODE_ENV"]
    }
  }
}

Cache Invalidation

# Manual cache clearing
turbo clean

# Selective cache clearing
turbo clean --dry-run
turbo clean apps/web

Environment Variables

Environment Management

// turbo.json environment variables
{
  "tasks": {
    "build": {
      "env": ["NODE_ENV", "API_URL"],
      "dependsOn": ["^build"]
    },
    "test": {
      "env": ["NODE_ENV", "DATABASE_URL"],
      "dependsOn": ["build"]
    }
  }
}

Local Development

# .env.local
NODE_ENV=development
API_URL=http://localhost:3001
DATABASE_URL=postgresql://localhost:5432/dev

Package Manager Integration

PNPM Workspaces

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
  - 'tools/*'

Yarn Workspaces

// package.json
{
  "workspaces": [
    "apps/*",
    "packages/*",
    "tools/*"
  ],
  "private": true
}

What We've Accomplished

✅ Workspace Configuration Complete:

  1. Set up basic Turborepo configuration
  2. Configured workspace structure and dependencies
  3. Implemented task dependencies and pipelines
  4. Set up advanced caching strategies
  5. Configured environment variables
  6. Integrated with package managers

Next Steps

With your workspace configured, let's explore how to define and run build pipelines.

Continue to Chapter 3: Task Pipelines

Generated by AI Codebase Knowledge Builder

What Problem Does This Solve?

Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for build, dependsOn, json so behavior stays predictable as complexity grows.

In practical terms, this chapter helps you avoid three common failures:

  • coupling core logic too tightly to one implementation path
  • missing the handoff boundaries between setup, execution, and validation
  • shipping changes without clear rollback or observability strategy

After working through this chapter, you should be able to reason about Chapter 2: Workspace Configuration as an operating subsystem inside Turborepo Tutorial: High-Performance Monorepo Build System, with explicit contracts for inputs, state transitions, and outputs.

Use the implementation notes around turbo, next, test as your checklist when adapting these patterns to your own repository.

How it Works Under the Hood

Under the hood, Chapter 2: Workspace Configuration usually follows a repeatable control path:

  1. Context bootstrap: initialize runtime config and prerequisites for build.
  2. Input normalization: shape incoming data so dependsOn receives stable contracts.
  3. Core execution: run the main logic branch and propagate intermediate state through json.
  4. Policy and safety checks: enforce limits, auth scopes, and failure boundaries.
  5. Output composition: return canonical result payloads for downstream consumers.
  6. Operational telemetry: emit logs/metrics needed for debugging and performance tuning.

When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.

Source Walkthrough

Use the following upstream sources to verify implementation details while reading this chapter:

  • View Repo Why it matters: authoritative reference on View Repo (github.com).

Suggested trace strategy:

  • search upstream code for build and dependsOn to map concrete implementation paths
  • compare docs claims against actual runtime/config code before reusing patterns in production

Chapter Connections