turborepo

name	turborepo
description	High-performance monorepo build system with intelligent caching and task orchestration
layer	domain
category	build-tools
triggers	["turborepo","turbo.json","turbo run","monorepo build","remote caching","task pipeline"]
inputs	["monorepo structure","workspace layout","build targets","caching requirements"]
outputs	["turbo.json config","pipeline definitions","filtering strategies","caching setup"]
linksTo	["monorepo","vercel","cicd","dev-workflow"]
linkedFrom	["monorepo","vercel","cicd"]
preferredNextSkills	["vercel","cicd","monorepo"]
fallbackSkills	["dev-workflow"]
riskLevel	low
memoryReadPolicy	selective
memoryWritePolicy	none
sideEffects	["build execution","cache writes"]

Turborepo

Purpose

Configure and optimize Turborepo for monorepo build orchestration — pipeline definitions, caching strategies, workspace filtering, and environment variable handling.

Key Patterns

Pipeline Configuration (turbo.json)

• Define tasks in tasks (v2) with dependsOn for topological ordering
• Use "dependsOn": ["^build"] to run dependencies' build first (caret = upstream)
• Set "outputs": [".next/**", "dist/**"] for correct cache artifacts
• Use "cache": false for tasks that must always run (e.g., deploy)
• "persistent": true for long-running dev servers

Caching and Hashing

• Turbo hashes source files, env vars, and task config to determine cache hits
• "globalEnv": ["CI", "NODE_ENV"] — env vars that invalidate all task caches
• "env": ["API_URL"] on a task — env vars scoped to that task's hash
• "globalPassThroughEnv" / "passThroughEnv" — accessible but not part of hash
• Remote caching via npx turbo login && npx turbo link (Vercel) or self-hosted

Filtering and Workspace Management

• turbo run build --filter=web — run only for the web workspace
• turbo run build --filter=web... — web and all its dependencies
• turbo run build --filter=...web — web and all its dependents
• turbo run build --filter={./apps/*} — glob-based workspace selection
• turbo run build --filter=[HEAD^1] — only workspaces changed since commit

Internal Packages Pattern

• Shared packages with "name": "@repo/ui" consumed via workspace protocol
• Use "main" / "exports" pointing to source (no build step) for internal-only packages
• Or add a build task with "dependsOn": ["^build"] for packages needing compilation

Anti-Patterns

Anti-Pattern	Fix