firtoz/turborepo

Turborepo Task Configuration

Patterns and best practices for configuring Turborepo tasks and dependencies in this monorepo.

When to Use This Skill

Use when:

• Adding new tasks to turbo.json files
• Configuring task dependencies between packages
• Setting up inputs/outputs for caching
• Creating cross-package dependencies
• Optimizing turbo cache configuration

Running Turbo Commands

Always run turbo commands from the workspace root.

# ✅ CORRECT - From workspace root
cd /workspace
bun run build        # Turbo builds all packages in correct order
bun run typecheck    # Turbo typechecks all packages
bun run lint         # Turbo lints all packages

# ❌ WRONG - From subdirectory
cd /workspace/apps/web
bun run build        # This bypasses turbo orchestration

Turbo automatically:

• Determines which packages need to run
• Figures out the correct order based on dependencies
• Parallelizes independent tasks
• Caches results for unchanged packages

You don't need --cwd or --filter flags - turbo handles everything.

Core Principles

1. Task Dependencies Should Use Outputs, Not Inputs

Bad:

// apps/web/turbo.json
"cf-typegen": {
  "inputs": [
    "wrangler.jsonc",
    "$TURBO_ROOT$/packages/scripts/src/cf-typegen.ts"  // ❌ Direct file reference
  ]
}

Good:

// apps/web/turbo.json
"cf-typegen": {
  "dependsOn": ["scripts#build"],  // ✅ Depends on package task
  "inputs": [
    "wrangler.jsonc"  // ✅ Only this package's files
  ]
}

Why: If task B depends on task A, B should depend on A's outputs, not A's inputs. Turbo handles the transitive dependency chain automatically.

2. Cross-Package Dependencies via package#task

When a package needs files from another package to be ready:

Step 1: Source package defines a build task

// packages/scripts/package.json
{
  "scripts": {
    "build": "echo '✓ scripts package ready'"  // Can be a no-op
  }
}

// packages/scripts/turbo.json
{
  "tasks": {
    "build": {
      "inputs": ["src/**/*.ts", "package.json"],
      "outputs": []
    }
  }
}

Step 2: Consumer package depends on package#build

// apps/web/turbo.json
{
  "tasks": {
    "generate-wrangler": {
      "dependsOn": ["scripts#build"],  // ✅ Cross-package dependency
      "inputs": ["wrangler.jsonc.hbs", "$TURBO_ROOT$/.env.local"]
    }
  }
}

Never do:

// ❌ DON'T reference other package's files directly
"inputs": ["$TURBO_ROOT$/packages/scripts/src/utils/file.ts"]

3. Task Definition Hierarchy

Tasks are defined in three places:

1. Root turbo.json - Global defaults and settings

   • Global outputLogs settings
   • Global env vars
   • Base task defaults

2. Package turbo.json - Package-specific tasks

   • Task-specific inputs/outputs
   • Task dependencies
   • Package-local configurations

3. Package package.json - Actual scripts

   • Must exist for turbo to run the task
   • Can be a simple echo for meta-tasks

4. Inputs and Outputs

Inputs - Files that affect the task output:

"inputs": [
  "src/**/*.ts",           // Source files
  "package.json",          // Dependencies
  "tsconfig.json",         // Configuration
  "$TURBO_ROOT$/.env.local" // Root-level files (use sparingly)
]

Outputs - Files generated by the task:

"outputs": [
  "dist/**/*",        // Build artifacts
  "*.d.ts",           // Type definitions
  ".next/**",         // Framework outputs
  "!.next/cache/**"   // Exclude from outputs
]

Rules:

• Only include files that actually affect the task
• Use globs for efficiency
• Outputs enable cache restoration
• Empty outputs [] means task always runs (but can still cache based on inputs)

Common Patterns

Pattern 1: Code Generation Task

// Task that generates code from a template
"generate-config": {
  "dependsOn": ["scripts#build"],           // Wait for scripts to be ready
  "inputs": [
    "config.template.json",                 // Template file
    "$TURBO_ROOT$/.env.local"               // Environment variables
  ],
  "outputs": ["config.json"]                // Generated file
}

Pattern 2: Type Generation from Generated Files

// Task that depends on generated files
"typegen": {
  "dependsOn": ["generate-config"],         // Wait for config generation
  "inputs": [
    "src/**/*.ts",                          // Source files
    "config.json"                           // Generated config (from previous task)
  ],
  "outputs": ["types/**/*.d.ts"]
}

Pattern 3: Build Task with External Dependencies

"build": {
  "dependsOn": ["^build", "typegen"],       // ^build = dependencies' build first
  "inputs": [
    "src/**/*",
    "public/**/*",
    "package.json",
    "tsconfig.json"
  ],
  "outputs": ["dist/**/*", ".next/**", "!.next/cache/**"]
}

Pattern 4: No-op Meta Task

// package.json
{
  "scripts": {
    "build": "echo '✓ Package ready'"       // Simple marker
  }
}

// turbo.json
{
  "tasks": {
    "build": {
      "inputs": ["src/**/*.ts"],            // Files that must be ready
      "outputs": []                         // No actual build output
    }
  }
}

Environment Variables

Global Env (available to all tasks)

// Root turbo.json
{
  "globalEnv": [
    "NODE_ENV",
    "CLOUDFLARE_API_TOKEN"
  ]
}

Task-specific Env

// Package turbo.json
{
  "tasks": {
    "deploy": {
      "env": ["DEPLOY_ENV", "API_TOKEN"],
      "cache": false  // Don't cache tasks with secrets
    }
  }
}

Caching Strategy

Cache Everything Possible

"build": {
  "inputs": ["src/**/*"],
  "outputs": ["dist/**"]
  // cache: true is default
}

Disable Cache for Side Effects

"deploy": {
  "cache": false,      // Deployment has side effects
  "dependsOn": ["build"]
}

"dev": {
  "cache": false,      // Dev server is persistent
  "persistent": true
}

Task Dependency Patterns

Sequential Dependencies

"task-c": {
  "dependsOn": ["task-a", "task-b"]  // Both must complete first
}

Topological Dependencies (workspace dependencies)

"build": {
  "dependsOn": ["^build"]  // Build all workspace dependencies first
}

Mixed Dependencies

"deploy": {
  "dependsOn": [
    "^build",              // Dependencies' build
    "build",                // Own build
    "scripts#pre-deploy"   // Specific package task
  ]
}

Common Mistakes

❌ Don't: Reference Other Package's Files Directly

"inputs": ["$TURBO_ROOT$/packages/utils/src/helper.ts"]

✅ Do: Depend on Other Package's Build Task

"dependsOn": ["utils#build"]

❌ Don't: Include All Files in Inputs

"inputs": ["**/*"]  // Too broad, slows down hashing

✅ Do: Be Specific with Inputs

"inputs": ["src/**/*.ts", "package.json", "tsconfig.json"]

❌ Don't: Forget to Define Outputs

"build": {
  "inputs": ["src/**/*"]
  // Missing outputs - turbo can't restore from cache
}

✅ Do: Always Define Outputs for Cacheable Tasks

"build": {
  "inputs": ["src/**/*"],
  "outputs": ["dist/**"]
}

Debugging

Check Task Graph

bun run build --graph
bun run build --dry-run

Inspect Cache

bun run build --summarize

Force No Cache

bun run build --force

Verbose Output

bun run build --verbose

This Project's Structure

Root turbo.json

• Global settings: globalDependencies, ui, task defaults
• Tasks: build, typecheck, typegen, cf-typegen, rr-typegen, dev, lint, pre-deploy, deploy, clean
• globalEnv: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, SESSION_SECRET

packages/scripts/turbo.json

• pre-deploy - Pre-deployment validation (inputs: wrangler.jsonc, .env.local)

apps/web/turbo.json

• typegen - Depends on cf-typegen, rr-typegen
• cf-typegen - Cloudflare Worker types (worker-configuration.d.ts)
• rr-typegen - React Router route types
• lint - Depends on typecheck
• typecheck - Depends on typegen
• build - Depends on typecheck
• deploy - Depends on scripts#pre-deploy, build, example-do#deploy, coordinator-do#deploy, processor-do#deploy

Durable objects (example-do, coordinator-do, processor-do)

• Each has its own turbo.json with deploy and other tasks as needed.

Key Dependency Chains

typegen → cf-typegen, rr-typegen
typecheck → typegen
lint → typecheck
build → typecheck
deploy → scripts#pre-deploy, build, example-do#deploy, coordinator-do#deploy, processor-do#deploy

Resources

• Turborepo Documentation
• Task Dependencies
• Caching
• Configuration