Turborepo Knowledge Patch

Turborepo Knowledge Patch

Use this skill when working with current Turborepo configuration, task execution, caching, repository analysis, developer tools, or supported package managers. Consult the topic reference that matches the work before changing an existing repository.

Reference index

Migrate deprecated interfaces

Use the current forms when replacing interfaces that warn in 2.9:

turbo run and turbo watch no longer use the daemon. TURBO_DAEMON, --daemon, --no-daemon, and the daemon configuration key are deprecated because they no longer have a role.

For the full migration and Future Flag details, read Migration and configuration.

Account for task-level cycle validation

Package Graph cycles no longer make Turborepo exit automatically. Turborepo validates the Task Graph instead: a task can run in a cyclic package graph when its task dependencies are not cyclic, while a relationship such as ^build still errors when it creates a Task Graph cycle.

{
  "tasks": {
    "simple-task": {},
    "build": { "dependsOn": ["^build"] }
  }
}

Read Repository analysis and structure for boundary checks, cycle diagnostics, graph devtools, and repository queries.

Compose long-running tasks with sidecars

A persistent task can use with to start other long-running tasks whenever it runs. This expresses runtime coexistence instead of the completion ordering imposed by dependsOn.

{
  "tasks": {
    "dev": {
      "with": ["api#start"],
      "persistent": true,
      "cache": false
    }
  }
}

To continue after failures but run a dependent task only when all of its dependencies succeeded, use:

turbo run test --continue=dependencies-successful

On SIGINT or SIGTERM, Turborepo forwards the signal to tasks and waits for their cleanup handlers. Press Ctrl+C again to force an immediate exit.

Read Task execution and inputs for watch cache writes, graph output, sidecar summaries, and profiling.

Hash generated and dependency outputs at the right time

Structured inputs objects can defer part of a task hash until upstream work is complete. Use mode: "jit" for files generated by a dependency. Use mode: "dependencyOutputs" to hash selected outputs of task dependencies.

{
  "tasks": {
    "codegen": { "cache": false },
    "build": {
      "dependsOn": ["codegen"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "!src/generated/**",
        { "mode": "jit", "globs": ["src/generated/**"] }
      ]
    },
    "check-types": {
      "dependsOn": ["^check-types"],
      "outputs": ["dist/**"],
      "inputs": [
        "$TURBO_DEFAULT$",
        {
          "mode": "dependencyOutputs",
          "globs": ["dist/**/*.d.ts"],
          "from": ["^check-types"]
        }
      ]
    }
  }
}

JIT inputs are hashed after dependencies finish. Dependency-output inputs let downstream tasks remain cached when an upstream implementation changes but the selected outputs do not.

Use $TURBO_ROOT$ to anchor an input glob at the workspace root:

{
  "tasks": {
    "build": { "inputs": ["$TURBO_ROOT$/important-file.txt"] }
  }
}

Intersect affected and filtered scopes

--affected and --filter can be combined. Only tasks or packages satisfying both constraints are selected, and filters can exclude packages from the affected set.

turbo run build --affected --filter=web
turbo run build --affected --filter=!docs
turbo query ls --affected --filter=my-app

turbo query affected emits structured JSON for changed tasks or packages. turbo query ls can return affected-only results and accept selectors. See Repository analysis and structure for the complete query forms.

Configure inheritance deliberately

Configuration may use turbo.jsonc; turbo.json also accepts trailing commas. A package-level turbo.json can extend // and another workspace package:

{
  "extends": ["//", "web"]
}

Put $TURBO_EXTENDS$ in an array to retain inherited values while adding local ones. Without it, the local array replaces the inherited array completely.

{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": ["$TURBO_EXTENDS$", ".next/**"]
    }
  }
}

Control local cache retention

Top-level cacheMaxAge and cacheMaxSize opt into age- and size-based local cache eviction. At the start of each turbo run, eviction removes expired artifacts and then the oldest artifacts needed to meet the size cap in a background thread.

{
  "cacheMaxAge": "7d",
  "cacheMaxSize": "10GB"
}

Linked Git worktrees share their local cache automatically with no configuration. For pruning, environment behavior, cache flags, and dependency- aware package-manager support, read Caching, environment, and package managers.

Inspect and observe runs

Use turbo devtools for live Package Graph and Task Graph views. Use turbo docs to search documentation from the terminal. For machine consumption, documentation routes can return Markdown and turbo query exposes structured repository data.

Experimental observability can export OpenTelemetry metrics. --json streams NDJSON structured logs, while --log-file writes structured logs without replacing normal terminal output. Read Developer tools and observability for the exact configuration and commands.