nx/docs/shared/features/cache-task-results.md

Cache Task Results

Rebuilding and retesting the same code repeatedly is costly. Nx offers a sophisticated and battle-tested computation caching system that ensures code is never rebuilt twice.

If you want to learn more about the conceptual model behind Nx's caching, read How Caching Works.

What gets cached?

Define Cacheable Tasks

{% tabs %} {% tab label="Nx >= 17" %}

To enable caching for build and test, edit the targetDefaults property in nx.json to include the build and test tasks:

{
  "targetDefaults": {
    "build": {
      "cache": true
    },
    "test": {
      "cache": true
    }
  }
}

{% /tab %} {% tab label="Nx < 17" %}

To enable caching for build and test, edit the cacheableOperations property in nx.json to include the build and test tasks:

{
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "test"]
      }
    }
  }
}

{% /tab %} {% /tabs %}

{% callout type="note" title="Cacheable operations need to be side effect free" %} This means that given the same input they should always result in the same output. As an example, e2e test runs that hit the backend API cannot be cached as the backend might influence the result of the test run. {% /callout %}

Now, if you run a build task twice, the operation will be instant the second time because it is restored from the cache.

{% terminal-video src="/documentation/shared/images/caching/cache-terminal-animation.mp4" alt="Video showing the terminal output of running a build command first without cache and then with cache. The 2nd run is almost instant, taking just 18ms" /%}

Nx restores both

• the terminal output
• The files and artifacts created from running the task (e.g., your build or dist directory)"

Keep reading to learn how to fine-tune what gets cached.

Fine-tune Caching with Inputs and Outputs

{% callout type="note" title="Detect Inputs and Outputs" %} Nx can automatically set inputs and outputs for you based on your tooling configuration settings when you use inferred tasks {% /callout %}

Nx's caching feature starts with sensible defaults, but you can also fine-tune the defaults to control exactly what gets cached and when. There are two main options that control caching:

• Inputs - define what gets included as part of the calculated hash (e.g. files, environment variables, etc.)
• Outputs - define folders where files might be placed as part of the task execution.

You can define these inputs and outputs at the project level (project.json) or globally for all projects (in nx.json).

Take the following example: we want to exclude all *.md files from the cache such that whenever we change the README.md (or any other markdown file), it does not invalidate the build cache. We also know that the build output will be stored in a folder named after the project name in the dist folder at the root of the workspace.

To achieve this, we can add an inputs and outputs definition globally for all projects or at a per-project level:

{% tabs %} {% tab label="Globally" %}

{
  "targetDefaults": {
    "build": {
      "inputs": ["{projectRoot}/**/*", "!{projectRoot}/**/*.md"],
      "outputs": ["{workspaceRoot}/dist/{projectName}"]
    }
  }
}

{% /tab %} {% tab label="Project Level" %}

{
  "name": "some-project",
  "targets": {
    "build": {
      ...
      "inputs": ["!{projectRoot}/**/*.md"],
      "outputs": ["{workspaceRoot}/dist/apps/some-project"],
      ...
    }
    ...
  }
}

{% /tab %} {% /tabs %}

Note, you only need to define output locations if they differ from the usual dist or build directory which Nx automatically recognizes.

Learn more about configuring inputs including namedInputs.

Where is the Cache Stored?

The cache is stored in .nx/cache by default. You can also change where the cache is stored if you want.

Enable Remote Caching

Enable remote caching by connecting to Nx Cloud:

npx nx connect

Learn more about remote caching.

Troubleshooting Caching

• debug cache misses
• turn off or skip the cache
• change the cache location
• clear the local or remote cache

---

Turn off or Skip the Cache

To ignore the cache (both reads and writes), use the --skip-nx-cache flag:

nx build header --skip-nx-cache

Alternatively, to disable caching for a specific task, ensure it is not part of the cached tasks. If you're using Nx Cloud, you can use --no-cloud to skip remote caching.

Clear the Local Cache

To clear the local cache, run:

npx nx reset

For more details refer to the nx reset page.