turborepo-caching

Turborepo Cache Configuration & Build Optimization

Skill Overview

Turborepo Caching is a set of build optimization solutions for JavaScript/TypeScript monorepo projects. With local and remote caching mechanisms, it significantly shortens build times and is well-suited for medium-to-large codebases that need frequent builds and tests.

Use Cases

1. Create a New Turborepo Project

When you start a new monorepo project, or need to configure Turborepo from scratch, this skill helps you quickly set up the turbo.json configuration file. It defines sensible pipeline dependency relationships and caching strategies, including directory structure planning, global dependency configuration, and environment variable setup.

2. CI/CD Build Optimization

If your team runs builds in continuous integration environments such as GitHub Actions, GitLab CI, or others, this skill provides a complete CI integration solution. By using the --filter parameter to build only the changed packages and sharing build artifacts via remote caching, you can reduce CI time from dozens of minutes to just a few.

3. Migrate an Existing Monorepo

When migrating from Lerna, Nx, or pnpm workspaces to Turborepo, this skill provides a smooth migration guide and configuration templates. You can keep your existing workspace structure and gradually introduce Turborepo’s caching and task scheduling capabilities, without needing to rewrite your entire build process at once.

Core Features

1. Pipeline Task Configuration

Use turbo.json to define the execution order and caching rules for various tasks in your project. Use dependsOn to declare task dependencies (e.g., build depends on ^build), use outputs to specify the artifact files to cache, and use inputs to precisely control the file scope that affects the cache hash. It also supports environment-variable-sensitive configuration and package-level custom pipelines.

2. Remote Caching Solutions

Supports two modes: Vercel’s official remote cache and a self-hosted cache server. The official solution can be connected with only npx turbo link, making it easy to get started. The self-hosted solution provides an Express example, suitable for enterprise environments that need private deployments. Caches can be shared between team members and CI, truly enabling “build once, reuse everywhere.”

3. Smart Filtering & Incremental Builds

Turborepo’s --filter syntax is very flexible and allows you to precisely control the build scope. For example, --filter=@myorg/web... builds only the specified packages and their dependencies, while --filter='...[origin/main]' builds only the packages that have changes relative to a branch. Combined with --dry-run and --graph, you can preview the task graph before actually running it.

Frequently Asked Questions

Where is the Turborepo cache saved?

By default, local cache is stored in the system user directory under the .turbo/cache folder (macOS/Linux: ~/.turbo, Windows: %LOCALAPPDATA%\turbo). If remote caching is configured, build artifacts are also uploaded to Vercel’s cloud service or your self-hosted server.

Why doesn’t the cache work (cache miss)?

The most common reasons include: outputs is not configured correctly, causing no files to be cached; inputs includes unnecessary files, causing the hash to change frequently; or environment variables change but are not declared in the env field. You can use turbo build --verbosity=2 to inspect the specific cache hashes and hit/miss status.

In CI, how do I build only the changed packages?

Use --filter together with branch-difference expressions. For example, in GitHub Actions you can run turbo build --filter='...[origin/main]'. This automatically detects packages and their dependency packages that have changed relative to the main branch. For Pull Requests, you can use --filter='...[base_ref]' to achieve a similar effect.

Is the remote cache free?

Vercel provides free quota for remote caching for individuals and small teams, though the exact limits may change. For large teams or enterprises, it’s recommended to use a self-hosted cache server. This skill provides a complete Express implementation example that can be deployed in any Node.js-supported environment.

What does the ^ symbol in dependsOn mean?

^ means “all dependency packages.” For example, "dependsOn": ["^build"] means the current package’s build task must wait for the build tasks of all workspace dependency packages to complete. This ensures that when you modify a shared component, the applications that depend on it will automatically rebuild.