Optimize Turborepo Build Caching

This skill guides Turborepo task configuration and caching for monorepos. It covers dependency ordering, cached artifacts, cache-key inputs, persistent development tasks, package-specific overrides, remote caching, and filtering work to affected packages. The examples connect build, test, lint, type-check, development, and deployment-related tasks through explicit configuration.

The core task fields describe different concerns: dependsOn orders prerequisite work, outputs identifies cached files, inputs influences cache keys, cache controls reuse, and persistent marks long-running processes. Root configuration can establish shared rules while an application-specific configuration extends and customizes them. Environment variables and global dependencies also participate in correctness.

Use it for a new Turborepo setup, a migration from another monorepo tool, remote-cache planning, pipeline optimization, or cache-miss debugging. First identify the installed Turbo version. The supplied JSON uses the Turbo 1.x pipeline key, while Turbo 2 uses tasks; adapt using the installed version's schema and migration guidance.

Explicit inputs replace defaults. Include $TURBO_DEFAULT$ or every real source, configuration, and dependency input needed for the task. An incomplete key can reuse stale build or test success. Do not cache artifacts containing secrets or reuse success when required external state is not bound to the key. Persistent development servers and side-effecting operations need appropriate cache exclusions.

Inputs include workspace packages, dependency relationships, generated artifacts, environment requirements, task scripts, and the intended remote-cache provider. Outputs are reviewed task configuration, package overrides, filtering commands, remote-cache access settings, and diagnostic observations. Inspect planned tasks and their cache inputs with this preview command:

turbo build --dry-run

Filters can select a package, its dependencies or dependents, a directory, multiple packages, exclusions, or changes relative to a revision. Over-filtering can omit necessary dependencies. Debugging patterns inspect task graphs, hashes, summaries, verbose output, and forced execution instead of assuming every missed hit is a cache-server problem.

Remote caching can share outputs between local development and CI. The Vercel example uses login and project linking, with token and team configuration supplied through CI storage. Keep tokens out of command arguments and logs, and do not give untrusted pull requests cache write access.

A self-hosted server needs a reviewed implementation of the installed protocol, authentication, server-derived tenant authorization, bounded artifacts, safe path and hash handling, atomic writes, stream-error handling, and retention. Untrusted identifiers must not become filesystem paths. Supported artifact signing requires an end-to-end check because shared cached outputs can contain executable build material.