{
    "name": "turborepo",
    "version": "1.0.0",
    "description": "Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines,\ndependsOn, caching, remote cache, the \"turbo\" CLI, --filter, --affected, CI optimization, environment\nvariables, internal packages, monorepo structure/best practices, and boundaries.\n\nUse when user: configures tasks/workflows/pipelines, creates packages, sets up\nmonorepo, shares code between apps, runs changed/affected packages, debugs cache,\nor has apps/packages directories.",
    "system_prompt": "name turborepo description Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines, dependsOn, caching, remote cache, the \"turbo\" CLI, --filter, --affected, CI optimization, environment variables, internal packages, monorepo structure/best practices, and boundaries. Use when user: configures tasks/workflows/pipelines, creates packages, sets up monorepo, shares code between apps, runs changed/affected packages, debugs cache, or has apps/packages directories. metadata {\"version\":\"2.9.19-canary.9\"} Turborepo Skill Build system for JavaScript/TypeScript monorepos. Turborepo caches task outputs and runs tasks in parallel based on dependency graph. IMPORTANT: Package Tasks, Not Root Tasks Prefer package tasks over Root Tasks. When creating tasks/scripts/pipelines, you MUST default to package tasks: Add the script to each relevant package's package.json Register the task in root turbo.json Root package.json only delegates via turbo run <task> DO NOT put task logic in root package.json when it can live in packages. This defeats Turborepo's parallelization. // DO THIS: Scripts in each package // apps/web/package.json { \"scripts\" : { \"build\" : \"next build\" , \"lint\" : \"eslint .\" , \"test\" : \"vitest\" } } // apps/api/package.json { \"scripts\" : { \"build\" : \"tsc\" , \"lint\" : \"eslint .\" , \"test\" : \"vitest\" } } // packages/ui/package.json { \"scripts\" : { \"build\" : \"tsc\" , \"lint\" : \"eslint .\" , \"test\" : \"vitest\" } } // turbo.json - register tasks { \"tasks\" : { \"build\" : { \"dependsOn\" : [ \"^build\" ] , \"outputs\" : [ \"dist/**\" ] } , \"lint\" : { } , \"test\" : { \"dependsOn\" : [ \"build\" ] } } } // Root package.json - ONLY delegates, no task logic { \"scripts\" : { \"build\" : \"turbo run build\" , \"lint\" : \"turbo run lint\" , \"test\" : \"turbo run test\" } } // DO NOT DO THIS - defeats parallelization // Root package.json { \"scripts\" : { \"build\" : \"cd apps/web && next build && cd ../api && tsc\" , \"lint\" : \"eslint apps/ packages/\" , \"test\" : \"vitest\" } } Root Tasks ( //#taskname ) are ONLY for tasks that truly cannot exist in packages, such as Vitest Projects' //#test , repo-wide release scripts, or tooling that does not invoke turbo itself. Secondary Rule: turbo run vs turbo Always use turbo run when the command is written into code: // package.json - ALWAYS \"turbo run\" { \"scripts\" : { \"build\" : \"turbo run build\" } } # CI workflows - ALWAYS \"turbo run\" - run: turbo run build --affected The shorthand turbo <tasks> is ONLY for one-off terminal commands typed directly by humans or agents. Never write turbo build into package.json, CI, or scripts. Quick Decision Trees \"I need to configure a task\" Configure a task? ├─ Define task dependencies → references/configuration/tasks.md ├─ Lint/check-types (parallel + caching) → Use Transit Nodes pattern (see below) ├─ Specify build outputs → references/configuration/tasks.md#outputs ├─ Handle environment variables → references/environment/RULE.md ├─ Set up dev/watch tasks → references/configuration/tasks.md#persistent ├─ Package-specific config → references/configuration/RULE.md#package-configurations └─ Global settings (cacheDir, daemon) → references/configuration/global-options.md \"My cache isn't working\" Cache problems? ├─ Tasks run but outputs not restored → Missing `outputs` key ├─ Cache misses unexpectedly → references/caching/gotchas.md ├─ Need to debug hash inputs → Use --summarize or --dry ├─ Want to skip cache entirely → Use --force or cache: false ├─ Remote cache not working → references/caching/remote-cache.md └─ Environment causing misses → references/environment/gotchas.md \"I want to run only changed packages\" Run only what changed? ├─ Changed packages + dependents (RECOMMENDED) → turbo run build --affected ├─ Custom base branch → --affected --affected-base=origin/develop ├─ Manual git comparison → --filter=...[origin/main] └─ See all filter options → references/filtering/RULE.md --affected is the primary way to run only changed packages. It automatically compares against the default branch and includes dependents. \"I want to filter packages\" Filter packages? ├─ Only changed packages → --affected (see above) ├─ By package name → --filter=web ├─ By directory → --filter=./apps/* ├─ Package + dependencies → --filter=web... ├─ Package + dependents → --filter=...web └─ Complex combinations → references/filtering/patterns.md \"Environment variables aren't working\" Environment issues? ├─ Vars not available at runtime → Strict mode filtering (default) ├─ Cache hits with wrong env → Var not in `env` key ├─ .env changes not causing rebuilds → .env not in `inputs` ├─ CI variables missing → references/environment/gotchas.md └─ Framework vars (NEXT_PUBLIC_*) → Auto-included via inference \"I need to set up CI\" CI setup? ├─ GitHub Actions → references/ci/github-actions.md ├─ Vercel deployment → references/ci/vercel.md ├─ Remote cache in CI → references/caching/remote-cache.md ├─ Only build changed packages → --affected flag ├─ Skip unnecessary builds → turbo-ignore (references/cli/commands.md) └─ Skip container setup when no changes → turbo-ignore \"I want to watch for changes during development\" Watch mode? ├─ Re-run tasks on change → turbo watch (references/watch/RULE.md) ├─ Dev servers with dependencies → Use `with` key (references/configuration/tasks.md#with) ├─ Restart dev server on dep change → Use `interruptible: true` └─ Persistent dev tasks → Use `persistent: true` \"I need to create/structure a package\" Package creation/structure? ├─ Create an internal package → references/best-practices/packages.md ├─ Repository structure → references/best-practices/structure.md ├─ Dependency management → references/best-practices/dependencies.md ├─ Best practices overview → references/best-practices/RULE.md ├─ JIT vs Compiled packages → references/best-practices/packages.md#compilation-strategies └─ Sharing code between apps → references/best-practices/RULE.md#package-types \"How should I structure my monorepo?\" Monorepo structure? ├─ Standard layout (apps/, packages/) → references/best-practices/RULE.md ├─ Package types (apps vs libraries) → references/best-practices/RULE.md#package-types ├─ Creating internal packages → references/best-practices/packages.md ├─ TypeScript configuration → references/best-practices/structure.md#typescript-configuration ├─ ESLint configuration → references/best-practices/structure.md#eslint-configuration ├─ Dependency management → references/best-practices/dependencies.md └─ Enforce package boundaries → references/boundaries/RULE.md \"I want to enforce architectural boundaries\" Enforce boundaries? ├─ Check for violations → turbo boundaries ├─ Tag packages → references/boundaries/RULE.md#tags ├─ Restrict which packages can import others → references/boundaries/RULE.md#rule-types └─ Prevent cross-package file imports → references/boundaries/RULE.md Critical Anti-Patterns Using turbo Shorthand in Code turbo run is recommended in package.json scripts and CI pipelines. The shorthand turbo <task> is intended for interactive terminal use. // WRONG - using shorthand in package.json { \"scripts\" : { \"build\" : \"turbo build\" , \"dev\" : \"turbo dev\" } } // CORRECT { \"scripts\" : { \"build\" : \"turbo run build\" , \"dev\" : \"turbo run dev\" } } # WRONG - using shorthand in CI - run: turbo build --affected # CORRECT - run: turbo run build --affected Root Scripts Bypassing Turbo Root package.json scripts MUST delegate to turbo run , not run tasks directly. // WRONG - bypasses turbo entirely { \"scripts\" : { \"build\" : \"bun build\" , \"dev\" : \"bun dev\" } } // CORRECT - delegates to turbo { \"scripts\" : { \"build\" : \"turbo run build\" , \"dev\" : \"turbo run dev\" } } Using && to Chain Turbo Tasks Don't chain turbo tasks with && . Let turbo orchestrate. // WRONG - turbo task not using turbo run { \"scripts\" : { \"changeset:publish\" : \"bun build && changeset publish\" } } // CORRECT { \"scripts\" : { \"changeset:publish\" : \"turbo run build && changeset publish\" } } prebuild Scripts That Manually Build Dependencies Scripts like prebuild that manually build other packages bypass Turborepo's dependency graph. // WRONG - manually building dependencies { \"scripts\" : { \"prebuild\" : \"cd ../../packages/types && bun run build && cd ../utils && bun run build\" , \"build\" : \"next build\" } } However, the fix depends on whether workspace dependencies are declared: If dependencies ARE declared (e.g., \"@repo/types\": \"workspace:*\" in package.json), remove the prebuild script. Turbo's dependsOn: [\"^build\"] handles this automatically. If dependencies are NOT declared , the prebuild exists because ^build won't trigger without a dependency relationship. The fix is to: Add the dependency to package.json: \"@repo/types\": \"workspace:*\" Then remove the prebuild script // CORRECT - declare dependency, let turbo handle build order // package.json { \"dependencies\" : { \"@repo/types\" : \"workspace:*\" , \"@repo/utils\" : \"workspace:*\" } , \"scripts\" : { \"build\" : \"next build\" } } // turbo.json { \"tasks\" : { \"build\" : { \"dependsOn\" : [ \"^build\" ] } } } Key insight: ^build only runs build in packages listed as dependencies. No dependency declaration = no automatic build ordering. Overly Broad globalDependencies globalDependencies affects ALL tasks in ALL packages via the global hash — tasks cannot opt out of specific files, even with negation globs in inputs . Be specific. // WRONG - heavy hammer, affects all hashes { \"globalDependencies\" : [ \"**/.env.*local\" ] } // BETTER - move to task-level inputs { \"globalDependencies\" : [ \".env\" ] , \"tasks\" : { \"build\" : { \"inputs\" : [ \"$TURBO_DEFAULT$\" , \".env*\" ] , \"outputs\" : [ \"dist/**\" ] } } } With futureFlags.globalConfiguration , this problem is reduced because global.inputs files are folded into each task's inputs (not the global hash). Tasks can exclude specific files: // BEST - global.inputs with per-task exclusion { \"futureFlags\" : { \"globalConfiguration\" : true } , \"global\" : { \"inputs\" : [ \".env\" ] } , \"tasks\" : { \"build\" : { \"outputs\" : [ \"dist/**\" ] } , \"lint\" : { \"inputs\" : [ \"$TURBO_DEFAULT$\" , \"!$TURBO_ROOT$/.env\" ] } } } Repetitive Task Configuration Look for repeated configuration across tasks that can be collapsed. Turborepo supports shared configuration patterns. // WRONG - repetitive env and inputs across tasks { \"tasks\" : { \"build\" : { \"env\" : [ \"API_URL\" , \"DATABASE_URL\" ] , \"inputs\" : [ \"$TURBO_DEFAULT$\" , \".env*\" ] } , \"test\" : { \"env\" : [ \"API_URL\" , \"DATABASE_URL\" ] , \"inputs\" : [ \"$TURBO_DEFAULT$\" , \".env*\" ] } , \"dev\" : { \"env\" : [ \"API_URL\" , \"DATABASE_URL\" ] , \"inputs\" : [ \"$TURBO_DEFAULT$\" , \".env*\" ] , \"cache\" : false , \"persistent\" : true } } } // BETTER - use globalEnv and globalDependencies for shared config { \"globalEnv\" : [ \"API_URL\" , \"DATABASE_URL\" ] , \"globalDependencies\" : [ \".env*\" ] , \"tasks\" : { \"build\" : { } , \"test\" : { } , \"dev\" : { \"cache\" : false , \"persistent\" : true } } } When to use global vs task-level: globalEnv / globalDependencies - affects ALL tasks, use for truly shared config Task-level env / inputs - use when only specific tasks need it NOT an Anti-Pattern: Large env Arrays A large env array (even 50+ variables) is not a problem. It usually means the user was thorough about declaring their build's environment dependencies. Do not flag this as an issue.",
    "model_config": {
        "provider": "deepseek",
        "model": "deepseek-chat",
        "temperature": 0.7,
        "max_tokens": 4096,
        "top_p": 0.9
    },
    "trigger_words": [],
    "source": "DeepseekModel",
    "source_url": "https://deepseekmodel.com/skill?id=antfu-skills-skills-turborepo-skill-md"
}