Turborepo, workspaces, package architecture, @repo/* naming, exports, tree-shaking
How this skill is triggered — by the user, by Claude, or both
Slash command
/infra-monorepo-turborepo:infra-monorepo-turborepoThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Quick Guide:** Turborepo 2.x for monorepo orchestration. Task pipelines with dependency ordering. Local + remote caching for massive speed gains. Workspaces for package linking. Syncpack for dependency version consistency. Internal packages use `@repo/*` naming, explicit `exports` fields, and `workspace:*` protocol.
Quick Guide: Turborepo 2.x for monorepo orchestration. Task pipelines with dependency ordering. Local + remote caching for massive speed gains. Workspaces for package linking. Syncpack for dependency version consistency. Internal packages use
@repo/*naming, explicitexportsfields, andworkspace:*protocol.
<critical_requirements>
All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
import type, named constants)
(You MUST define task dependencies using dependsOn: ["^build"] in turbo.json to ensure topological ordering)
(You MUST declare all environment variables in the env array of turbo.json tasks for proper cache invalidation)
(You MUST set cache: false for tasks with side effects like dev servers and code generation)
(You MUST use Bun workspaces protocol workspace:* for internal package dependencies)
(You MUST use @repo/* naming convention for ALL internal packages)
(You MUST define explicit exports field in package.json - never allow importing internal paths)
(You MUST mark React as peerDependencies NOT dependencies in component packages)
</critical_requirements>
Auto-detection: Turborepo configuration, turbo.json, monorepo setup, workspaces, Bun workspaces, syncpack, task pipelines, @repo/* packages, package.json exports, workspace dependencies, shared configurations
When to use:
packages/When NOT to use:
Key patterns covered:
Detailed Resources:
Turborepo is a high-performance build system designed for JavaScript/TypeScript monorepos. It provides intelligent task scheduling, caching, and remote cache sharing to dramatically reduce build times. Combined with Bun workspaces, it enables efficient package management with automatic dependency linking.
When to use Turborepo:
When NOT to use Turborepo:
Define task dependencies and caching behavior in turbo.json to enable intelligent build orchestration and caching.
dependsOn: ["^build"] - Run dependency tasks first (topological order)outputs - Define what files to cacheinputs - Specify which files trigger cache invalidationcache: false - Disable caching for tasks with side effectspersistent: true - Keep dev servers running// Good Example - Proper task configuration with dependencies
{
"tasks": {
"build": {
"dependsOn": ["^build"],
"env": ["DATABASE_URL", "NODE_ENV"],
"outputs": ["dist/**", ".next/**", "!.next/cache/**"]
},
"test": {
"dependsOn": ["^build"],
"inputs": [
"$TURBO_DEFAULT$",
"src/**/*.tsx",
"src/**/*.ts",
"test/**/*.ts",
"test/**/*.tsx"
]
},
"dev": {
"cache": false,
"persistent": true
},
"generate": {
"dependsOn": ["^generate"],
"cache": false
},
"lint": {}
}
}
Why good: dependsOn: ["^build"] ensures topological task execution (dependencies build first), env array includes all environment variables for proper cache invalidation, cache: false prevents caching tasks with side effects (dev servers, code generation), outputs specifies cacheable artifacts while excluding cache directories
See examples/core.md for good/bad comparison examples.
Turborepo's caching system dramatically speeds up builds by reusing previous task outputs when inputs haven't changed.
dist/, .next/)cache: true)cache: false)cache: false - generates files)env array).env, tsconfig.json)Setup: Link Vercel account, set TURBO_TOKEN and TURBO_TEAM environment variables to enable remote cache sharing.
See examples/caching.md for remote caching configuration and CI integration examples.
Configure Bun workspaces to enable package linking and dependency sharing across monorepo packages.
// Good Example - Properly configured workspaces
{
"workspaces": ["apps/*", "packages/*"],
"dependencies": {
"@repo/ui": "workspace:*",
"@repo/types": "workspace:*"
}
}
Why good: workspace:* protocol links local packages automatically, glob patterns apps/* and packages/* discover all packages dynamically, Bun hoists common dependencies to root reducing duplication
my-monorepo/
├── apps/
│ ├── web/ # Frontend application
│ ├── admin/ # Admin dashboard
│ └── server/ # Backend server
├── packages/
│ ├── ui/ # Shared UI components
│ ├── api/ # API client
│ ├── eslint-config/ # Shared ESLint config
│ ├── prettier-config/ # Shared Prettier config
│ └── typescript-config/ # Shared TypeScript config
├── turbo.json # Turborepo configuration
└── package.json # Root package.json with workspaces
See examples/workspaces.md for workspace protocol good/bad comparison examples.
Cache Hit Metrics:
Optimization Strategies:
globalDependencies for files affecting all packages (.env, tsconfig.json) to prevent unnecessary cache invalidationinputs array to fine-tune what triggers cache invalidation for specific tasks--filter with affected detection (--filter=...[HEAD^]) to only run tasks for changed packagesoutputs carefully to exclude cache directories (e.g., !.next/cache/**)Force Cache Bypass:
# Ignore cache when needed
bun run build --force
# Only build affected packages
bun run build --filter=...[HEAD^1]
<decision_framework>
New code to write?
├─ Is it a deployable application? → apps/
├─ Is it shared across 2+ apps? → packages/
├─ Is it app-specific? → Keep in app directory
└─ Is it a build tool? → tools/
Is this a monorepo with multiple packages/apps?
├─ NO → Use standard build tools
└─ YES → Do builds take > 30s or is caching important?
├─ YES → Use Turborepo
└─ NO → Standard tools may suffice
For comprehensive decision trees and package creation criteria, see reference.md.
</decision_framework>
<red_flags>
High Priority Issues:
dependsOn: ["^build"] for build tasks (breaks topological ordering)env array in turbo.json (causes cache misses across environments)exports field in package.json (allows internal path imports)Common Mistakes:
workspace:* for internal depsdependencies instead of peerDependencies--filter=...[HEAD^] affected detectionGotchas:
dependsOn: ["^task"] runs dependencies' tasks; dependsOn: ["task"] runs same package's task--filter=...[HEAD^] requires fetch-depth: 2 in GitHub Actions!.next/cache/**For detailed anti-patterns and checklists, see reference.md.
</red_flags>
<critical_reminders>
All code must follow project conventions in CLAUDE.md
(You MUST define task dependencies using dependsOn: ["^build"] in turbo.json to ensure topological ordering)
(You MUST declare all environment variables in the env array of turbo.json tasks for proper cache invalidation)
(You MUST set cache: false for tasks with side effects like dev servers and code generation)
(You MUST use Bun workspaces protocol workspace:* for internal package dependencies)
(You MUST use @repo/* naming convention for ALL internal packages)
(You MUST define explicit exports field in package.json - never allow importing internal paths)
(You MUST mark React as peerDependencies NOT dependencies in component packages)
Failure to follow these rules will cause incorrect builds, cache misses, broken dependency resolution, and tree-shaking failures.
</critical_reminders>
npx claudepluginhub agents-inc/skills --plugin infra-monorepo-turborepoGuides Turborepo monorepo management: workspace creation, turbo.json task configuration, Next.js/NestJS app setup, Vitest/Jest test pipelines, CI/CD workflows, remote caching, and build optimization for TypeScript/JavaScript projects.
Configures Turborepo pipelines for monorepo caching to speed up builds and CI/CD. Includes turbo.json templates, remote Vercel setup, and optimization tips.
Configures Turborepo for efficient monorepo builds with local and remote caching, pipeline optimization, and CI/CD integration.