Turborepo

Turborepo - Monorepo Architecture Expert

Assumption: You know turbo run build. This covers architectural decisions.

Arguments

• $ARGUMENTS: Monorepo decision, package boundary, or cache issue to analyze
• Example: /turborepo why is turbo cache missing in CI
• Example: /turborepo should packages/ui be split from packages/web-core
• If empty: ask which Turborepo architecture problem is in scope

---

Before Adopting Turborepo: Strategic Assessment

Break-even: Monorepo worth it when 3+ apps share 30%+ code AND frequent coordination is required.

---

Critical Rule: Package Tasks, Not Root Tasks

The #1 Turborepo mistake: Putting task logic in root package.json.

// WRONG - defeats parallelization
// Root package.json
{ "scripts": { "build": "cd apps/web && next build && cd ../api && tsc" } }

// CORRECT - each package owns its task
// apps/web/package.json
{ "scripts": { "build": "next build" } }

// Root package.json - ONLY delegates
{ "scripts": { "build": "turbo run build" } }

Why: Turborepo can't parallelize sequential shell commands. Package tasks enable task graph parallelization.

---

Decision: When to Split a Package

Considering splitting code into a package?
│
├─ Used by 1 app only → DON'T split yet
│   └─ Keep in app; wait for second consumer
│      WHY: Premature abstraction, overhead > benefit
│
├─ Used by 2+ apps → MAYBE split
│   ├─ Stable API (rarely changes) → Split
│   ├─ Unstable (changes every sprint) → DON'T split yet
│   └─ Mixed team ownership → DON'T split (use import path)
│      WHY: Shared packages need stable APIs + clear owners
│
├─ Publishing to npm → MUST split
│
└─ CI builds > 10min → Split by stability, not domain
    └─ Stable packages cache; unstable packages always rebuild

Anti-pattern: Creating packages for "clean architecture" with no consumers. Every package adds build, test, and version overhead.

---

Anti-Patterns

❌ #1: Circular Dependencies

Symptom: turbo run build fails with "Could not resolve dependency graph"

packages/ui → packages/utils
packages/utils → packages/ui  // circular

Fix: Extract shared code to a third package (packages/shared).

For indirect cycles (A → B → C → A), use: npx madge --circular --extensions ts,tsx packages/

❌ #2: Overly Granular Packages

Symptom: Every feature touches 5+ packages; 10+ version bumps per sprint; pnpm workspace:* version hell.

Fix: Group by change frequency, not by domain:

packages/ui/            # All components (changes often)
packages/ui-primitives/ # Headless components (stable)
packages/icons/         # Generated SVGs (rarely changes)

Rule: Package boundary = different change frequency. Packages that always change together should be one package.

❌ #3: Missing Task Dependencies

Symptom: Tests pass locally, fail in CI with "Cannot find module './dist/index.js'"

Cause: Tests run before build completes — race condition.

// WRONG - no dependsOn for test
{ "tasks": { "build": { "outputs": ["dist/**"] }, "test": {} } }

// CORRECT
{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "test": { "dependsOn": ["build"] }
  }
}

`^build` = build this package's dependencies first. `build` = build this package first.

❌ #4: Cache Miss Hell

Symptom: Cache never hits; every run rebuilds everything.

Cause: inputs glob too broad — comment changes trigger rebuild.

// WRONG
{ "build": { "inputs": ["src/**"] } }

// CORRECT
{ "build": { "inputs": ["src/**/*.{ts,tsx}", "!src/**/*.test.ts"] } }

Debug:

turbo run build --dry --graph          # Visualize task graph
turbo run build --dry=json | jq '.tasks[] | select(.cache.status == "MISS")'

---

Decision: Monorepo vs Polyrepo

Starting new project?
│
├─ Single team, single product → Polyrepo (simpler)
│
├─ Shared UI library → Monorepo
│   └─ Develop library + test in consumers simultaneously
│
├─ Microservices in different languages → Polyrepo
│   └─ Turborepo is JS/TS focused
│
└─ Multiple teams, shared code, atomic changes needed → Monorepo

Practical advice: Start polyrepo, migrate to monorepo when the cross-repo coordination pain exceeds the tooling cost.

---

Package Boundary Patterns

By stability (recommended):

packages/core/      # Changes quarterly (semantic versioning)
packages/features/  # Changes weekly (workspace protocol)
packages/utils/     # Changes monthly

By consumer:

packages/public-api/  # External consumers — strict versioning
packages/internal/    # Internal apps — workspace protocol OK

By team: Only works if teams rarely share code. Otherwise creates silos.

---

Turborepo vs Alternatives

---

Error Recovery

Cache never hits

1. turbo run build --dry=json | jq '.tasks[0].hash' — see current hash 2. Narrow inputs glob to exclude non-code files 3. Fallback: "cache": false in turbo.json temporarily to debug without cache pressure

Circular dependency error

1. turbo run build --dry --graph=graph.html — visualize in browser 2. npx madge --circular --extensions ts,tsx packages/ — for indirect cycles 3. Extract common code to packages/shared

Tests fail in CI but pass locally

1. turbo run test --dry --graph — verify build runs before test 2. Add "dependsOn": ["build"] to test task 3. turbo run test --force — bypass cache to confirm ordering

Overly granular packages causing version hell

1. git log --oneline --since="1 month ago" -- packages/ — count version bumps per package 2. Packages that change together 5+ times → merge them 3. Fallback: use workspace:* to auto-link versions while planning merge

---

When to Load Full Reference

READ `references/cli-options.md` when: encountering 3+ unknown CLI flags, need advanced --filter patterns across 10+ packages, or setting up complex pipeline options.

READ `references/remote-cache-setup.md` when: setting up remote cache for teams, debugging cache auth errors, or configuring self-hosted cache with custom storage.

Do NOT load references for: basic architecture decisions, single cache miss debugging, or monorepo adoption decisions — all covered above.

---

Resources

• Official Docs: https://turbo.build/repo/docs

turborepo - Monorepo Architecture Expert

Version: 3.0.0 Grade: F → C (28/120 → ~72/120) Token Reduction: 914 lines → ~330 lines (64% reduction)

What This Skill Does

Turborepo monorepo architectural decisions and anti-patterns. NOT CLI syntax reference - focuses on when to split packages and avoiding monorepo sprawl.

TDD Improvements Applied

1. Description Quality (RED → GREEN)

Problem: Description listed CLI topics (turbo.json, --filter, --affected) Test Failed: No architectural decision triggers

Fix:

• Added 5 architecture decision scenarios
• Clear negative scope: "NOT for CLI syntax"
• Focus keywords: package boundaries, when to split, circular dependencies

Result: ✅ Agent loads for architecture, not CLI help

2. Knowledge Delta (RED → GREEN)

Problem: 85% CLI documentation (turbo --help equivalent) Test Failed: Not expert knowledge

Removed (580+ lines):

• CLI flag reference
• turbo.json schema documentation
• Command syntax examples

Added (330 lines of expert insights):

• When to split package decision tree
• 4 critical anti-patterns (circular deps, over-granularity, cache misses)
• Monorepo vs polyrepo decision framework
• Package boundary patterns (by stability, by consumer, by team)

Result: ✅ 75% expert knowledge (was 15%)

3. Anti-Patterns Added

1. Circular Dependencies - Breaks task graph 2. Overly Granular Packages - 50 micro-packages, version hell 3. Missing Task Dependencies - Tests run before build 4. Cache Miss Hell - Broad inputs, constant rebuilds

Result: ✅ Prevents common monorepo architecture failures

4. Decision Frameworks

1. When to Split Package - Based on consumers, stability, ownership 2. Monorepo vs Polyrepo - Team size, shared code, language mix 3. Package Boundaries - By stability, by consumer, by team

Result: ✅ Clear criteria for all architectural decisions

Key Features

Critical Rule

Package Tasks, Not Root Tasks - The #1 Turborepo mistake

// ❌ WRONG - defeats parallelization
"scripts": { "build": "cd apps/web && next build" }

// ✅ CORRECT - parallel execution
// Each package has own build task

When to Split Package

1 consumer → Keep inline
2-3 consumers + stable → Split
4+ consumers → Split
Unstable API → Don't split yet

Anti-Patterns

• Circular dependencies break task graph
• 50 micro-packages = version hell
• Missing dependsOn = tests fail
• Broad cache inputs = constant rebuilds

Turborepo vs Alternatives

• Turborepo: JS/TS, Next.js/React
• Nx: Polyglot, opinionated structure
• Rush: 100+ packages, npm publishing

Installation

cp -r turborepo ~/.agents/skills/

Resources

• Official Docs: https://turbo.build/repo/docs (CLI reference)
• This Skill: Architecture decisions, anti-patterns