If Your Turborepo Cache Hit Rate Is Low, the Cause Is Almost Always `dependsOn`, `inputs`, or `outputs` in `turbo.json`

If you've adopted Turborepo in a monorepo but the cache isn't hitting properly, the cause is almost always one of three things in turbo.json: inputs, outputs, or dependsOn. The whole build re-running after editing a single line in README.md, or the cache showing a hit but the dist/ folder being empty — I spent a long time struggling with both of these when I first integrated Turborepo. Getting the execution order right with dependsOn, narrowing the hash calculation scope with inputs, and explicitly specifying the build artifact paths with outputs — these three things determine your Turborepo cache hit rate.

Turborepo is a build system for JavaScript/TypeScript monorepos developed by Vercel. Its core feature is task caching — in a structure where multiple packages live in a single repository, it avoids rebuilding what has already been built. Before executing a task, it calculates a hash of the inputs, and if the same hash already exists in the cache, it skips re-execution. You specify the hash calculation scope and artifact storage paths directly in turbo.json.

This article examines what each of the three settings does, what symptoms appear when a value is wrong, and configuration patterns you can use directly in production. At the end, you'll find a turbo.json template you can copy and apply today.

Core Concepts

How Turborepo Determines Cache Hits

Before executing a task, Turborepo creates a "fingerprint" for that task. It calculates this fingerprint by combining the contents of files specified in inputs, the values of environment variables declared in env, and the hash of upstream tasks connected via dependsOn. If a cache entry with the same hash exists from a previous run, it restores the files specified in outputs and skips execution.

Input file hash + Environment variable values + Dependent task hash
            ↓
       Cache Key
            ↓
   Hit → Restore artifacts / Miss → Actually execute

The three settings each handle a different stage of this flow.

dependsOn — Execution Order Must Be Correct for the Cache to Mean Anything

dependsOn is used in two forms. With the ^ prefix, it runs the same-named task in the packages the current package depends on (dependencies/devDependencies in package.json) first. Without the prefix, it refers to a different task within the same package.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}

^build — Runs the build task of all packages the current package depends on first. This prevents the current package's build from starting before the build artifacts of its dependency packages are ready.

Here, test.dependsOn: ["build"] (no caret) means the same package's build must complete first. This pattern is needed when tests reference build artifacts like type declaration files (.d.ts). For simple unit tests that don't depend on build output, you can omit this entry.

If you want to explicitly specify only a particular package, you can also use the "pkg-a#build" format. This is useful in situations where explicit specification is clearer — such as when a specific shared library must be built first, rather than relying on automatic dependency graph traversal.

inputs — The Narrower the Hash Scope, the Higher the Hit Rate

If you leave the default as-is, all Git-tracked files inside the package directory are included in the hash calculation. Git-tracked files means all files that Git detects changes in — those not excluded by .gitignore. This is why the build cache gets invalidated when you only touch documentation or test fixtures.

{
  "tasks": {
    "build": {
      "inputs": ["src/**", "package.json", "tsconfig.json"]
    },
    "lint": {
      "inputs": ["src/**", ".eslintrc.*"]
    },
    "test": {
      "inputs": ["src/**", "tests/**", "jest.config.*"]
    }
  }
}

There's one important caveat here. The moment you explicitly specify inputs, the automatic exclusion logic based on .gitignore is disabled. If you want to maintain the default behavior while excluding only specific files, it's much safer to use the $TURBO_DEFAULT$ microsyntax.

{
  "tasks": {
    "lint": {
      "inputs": ["$TURBO_DEFAULT$", "!README.md", "!CHANGELOG.md"]
    }
  }
}

$TURBO_DEFAULT$ — Including this in inputs preserves the default behavior of "all files in the package tracked by Git." You can then append !pattern to selectively exclude files, making it much safer than completely replacing the default behavior.

outputs — Omitting This Makes Cache Hits Meaningless

Honestly, I think this is where I wasted the most time. If you don't configure outputs, Turborepo caches execution logs but does not store the build artifact files. This means even when a cache hit occurs, the dist/ folder is empty, and downstream package builds that need those files will ultimately fail.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": [
        "dist/**",
        ".next/**",
        "!.next/cache/**"
      ]
    },
    "test": {
      "inputs": ["src/**", "tests/**"],
      "outputs": ["coverage/**"]
    }
  }
}

There's a reason .next/cache/** is excluded with !. If Turborepo stores the internal build cache directory that Next.js manages on its own, the cache store grows unnecessarily large, and the hit rate can actually drop as this large directory is serialized and deserialized every time.

Practical Application

Example 1: Full turbo.json Configuration for a Typical Monorepo

This is the configuration you'll most commonly see in production, reproduced as-is. Starting with Turborepo 2.x, the recommended approach is to define tasks directly under tasks rather than the old pipeline key (pipeline still works for backward compatibility, but new projects should use tasks).

In this configuration, the item I made mistakes with most often is test.dependsOn. I recommend only including ["^build"] when the build result must come first — such as for tests that reference type declaration files. In projects where this isn't the case, removing this entry can reduce unnecessary serial execution.

{
  "$schema": "https://turbo.build/schema.json",
  "globalEnv": ["NODE_ENV", "CI"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tests/**", "jest.config.*"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "inputs": ["$TURBO_DEFAULT$", "!README.md", "!*.md"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

The intent behind each setting is summarized below.

Example 2: Reflecting Environment Variables in the Cache Key

If environment variables like API_URL or NEXT_PUBLIC_* change but old build artifacts are still being restored, those variables are not declared in env or globalEnv. This is the most dangerous case — it silently deploys incorrect artifacts.

In particular, Next.js's NEXT_PUBLIC_* variables are inlined directly into the bundle at build time, not at runtime. If these values change, the build artifact itself changes, so they must be reflected in the cache key. If staging and production use different NEXT_PUBLIC_API_URL values, without this variable in env, both environments will reuse the same cache.

{
  "globalEnv": ["NODE_ENV", "CI"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["API_URL", "NEXT_PUBLIC_APP_VERSION"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**"]
    }
  }
}

globalEnv vs env — globalEnv is for global environment variables that affect the cache key of all tasks. Variables like NODE_ENV or CI that can change results in any task belong here. Variables only relevant to a specific task should be declared in that task's env array for greater precision.

Starting with Turborepo 2.2, a warning is printed when a task uses an environment variable not declared in turbo.json. Paying close attention to these warnings when first introducing Turborepo is a big help for finding missing environment variables.

Example 3: Tracing Why Cache Misses Are Occurring

A workflow for tracking which files are changing the hash when the cache hit rate is lower than expected. This is the sequence I follow whenever cache misses are frequent in CI.

# 1. Check which tasks will run without actually executing
turbo run build --dry=json
 
# 2. Run twice to check if the hash changes
turbo run build --summarize
# Compare the inputs section in the JSON files in the .turbo/runs/ folder
 
# 3. Run only tasks affected by changed packages (useful for PR build optimization)
turbo run build --affected

Using the --summarize option generates a run summary JSON in the .turbo/runs/ folder. If the hash values differ between two runs of the same task, you can compare the inputs entries in the JSON files to immediately find which files changed.

--affected is more of an optimization option for "running only tasks affected by changed packages" than a cache debugging tool, so its role is slightly different. It can be used in situations with limited change scope — like PR builds — to run only the necessary tasks instead of the full build.

Pros and Cons Analysis

Pros

Cons and Caveats

Most Common Mistakes in Production

If the cons table is a summary of "what the problems are," the following is about what these mistakes actually lead to in the field.

1. Not using outputs at all — FULL TURBO is printed in the build log, but the dist/ folder is empty, causing the next package build to fail entirely. This is a classic pattern where you spend hours wondering why the build is breaking when the cache clearly seems to have hit.
2. Leaving inputs at the default — Updating a single line in CHANGELOG.md causes the entire monorepo build to re-run. When you open the turbo.json of teams with low CI cache hit rates, the inputs entry is usually missing entirely.
3. Not declaring environment variables in env — Staging and production use different API_URL values, but the same bundle is restored for both environments. The problem is that discovery itself is delayed because incorrect artifacts are deployed without any errors.

Closing Thoughts

Explicitly specifying outputs to store artifacts in the cache, narrowing the hash scope with inputs to focus on source files, and declaring environment variables in env or globalEnv — just getting these three right will bring a noticeable improvement in your Turborepo cache hit rate.

There are 3 steps you can start with right now.

1. You can examine your current task configuration with the turbo run build --dry=json command. If there are tasks with empty outputs, those are the top priority for improvement — just filling in this field will start restoring build artifacts correctly after cache hits.
2. You can run turbo run build --summarize twice in a row and compare the hash values in the JSON files in the .turbo/runs/ folder. If the hash changes, check the inputs section for which files changed, then exclude those files from inputs or narrow them down with a $TURBO_DEFAULT$ and !pattern combination to reduce unnecessary cache misses.
3. You can check whether environment variables referenced via process.env in a task are declared in env or globalEnv. If you're using Turborepo 2.2 or above, the warning messages printed at build time will greatly reduce the work of finding missing variables, and this check alone can prevent incorrect cache restoration issues between staging and production.

References

• Turborepo Official Docs — Caching
• Turborepo Official Docs — Configuring Tasks
• Turborepo Official Docs — turbo.json Reference
• Turborepo Official Docs — Using Environment Variables
• Turborepo Troubleshooting Runs
• Turborepo 2.5 Release Notes
• Turborepo 2.2 Release Notes