Turborepo Caching

What Is Turborepo Caching?

Turborepo Caching is a set of production patterns and configurations for optimizing build performance in JavaScript and TypeScript monorepos managed with Turborepo. This skill focuses on leveraging Turborepo's local and remote caching mechanisms to minimize redundant work, accelerate build pipelines, and streamline development workflows across teams and environments.

Turborepo is a high-performance build system for monorepos, and caching is at the heart of its efficiency. By understanding and configuring caching correctly, teams can achieve faster builds, more reliable continuous integration (CI) processes, and improved developer experience. This skill is essential for teams setting up new Turborepo projects, migrating from other monorepo tools, or optimizing existing pipelines for scale and speed.

Why Use Turborepo Caching?

Monorepos often suffer from slow builds due to the number of interconnected packages and applications. Without intelligent caching, every build step is executed from scratch, leading to inefficiencies and wasted CI resources. Turborepo addresses this problem by:

• Caching build outputs: Results of commands like build, lint, and test are saved and reused if neither the inputs nor the dependencies have changed.
• Distributed caching: Remote caches allow teams and CI pipelines to share build artifacts, eliminating redundant work across environments.
• Incremental builds: Only affected packages or apps are rebuilt, not the entire monorepo.

These caching features lead to:

• Dramatically reduced build and test times
• Lower CI/CD costs
• Faster feedback for developers
• Consistent reproducibility of builds across machines and environments

How to Use Turborepo Caching

To take full advantage of caching in Turborepo, you must correctly define your build pipeline, outputs, and cache configuration in the turbo.json file at the root of your workspace. Below are the key steps and concepts.

1. Monorepo

Structure

A typical Turborepo project is structured as follows:

Workspace Root/
├── apps/
│   ├── web/
│   └── docs/
├── packages/
│   ├── ui/
│   └── config/
├── turbo.json
└── package.json

Here, apps/ contains deployable applications, and packages/ contains shared code or configurations.

2. Defining the

Pipeline

The pipeline section of turbo.json defines tasks, their dependencies, and caching behavior:

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env", ".env.local"],
  "globalEnv": ["NODE_ENV", "VERCEL_URL"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", "build/**"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "cache": true
    },
    "lint": {
      "outputs": [],
      "inputs": ["src/**", ".eslintrc.json"]
    },
    "test": {
      "outputs": [],
      "inputs": ["src/**", "jest.config.js"]
    }
  }
}

Key options explained:

• dependsOn: Specifies other tasks that must run first. The ^build syntax means "build" in dependencies.
• outputs: Lists files or directories that should be cached if the task is successful.
• inputs: Files or globs that impact the cache key for this task.
• cache: Enables or disables caching for the task. Defaults to true if not specified.

3. Local and Remote

Caching

Turborepo caches outputs locally by default in the .turbo directory. For distributed teams or CI/CD, configure remote caching to sync cache artifacts across environments:

Remote cache example using Vercel:

npx turbo login
npx turbo link

This connects your project to Vercel Remote Cache, allowing cache hits across developer machines and CI.

Custom remote cache configuration is also possible using file storage, Redis, or cloud providers (see Turborepo docs for details).

4. Debugging Cache

Issues

You can debug cache behavior with:

npx turbo run build --debug

This outputs detailed information about cache hits, misses, and the reasoning behind each.

Common issues include:

• Not specifying all relevant files in inputs
• Forgetting to list all output files and folders in outputs
• CI environments not sharing the same cache

When to Use Turborepo Caching

Use this skill when:

• Initializing new Turborepo monorepos and designing build pipelines
• Migrating from other monorepo tools (like Lerna or Nx) to Turborepo
• Implementing or troubleshooting remote caching for distributed development teams
• Optimizing CI/CD workflows to minimize build times and cost
• Investigating or debugging cache misses that lead to redundant or slow builds

Important Notes

• Explicit outputs and inputs are critical: If you do not correctly list all files relevant to a task, Turborepo may miss cache hits or produce stale results.
• Remote caching setup is essential for CI: Without remote caching, each CI run starts from scratch, negating the benefits of caching.
• Sensitive files: Avoid caching outputs that include secrets or environment-specific data.
• Persistent tasks: For long-running tasks (like development servers), set "persistent": true in the pipeline to prevent Turborepo from caching or terminating them.
• Global dependencies: Use globalDependencies to include files like .env that, when changed, should invalidate caches across the workspace.

By carefully configuring your Turborepo pipeline and leveraging both local and remote caching, you can dramatically improve build efficiency and reliability for complex monorepos.