Cache Task Results

It's costly to rebuild and retest the same code over and over again. Nx has the most sophisticated and battle-tested computation caching system to make sure it never rebuilds the same code twice. It knows when the task you are about to run, has been executed before, so it can use the cache to restore the results of running that task.

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

Define Cacheable Tasks

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

nx.json
1{ 2 "targetDefaults": { 3 "build": { 4 "cache": true 5 }, 6 "test": { 7 "cache": true 8 } 9 } 10} 11
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.

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

Nx restores both

  • the terminal output
  • the files & artifacts created as a result of running the task (e.g. your build or dist directory)

Keep reading for learning how to further fine-tune what gets cached.

Fine-tune Caching with Inputs and Outputs

You can control what ends up being cached and therefore fine-tune the defaults to better match your needs. There are two main mechanisms for this:

  • Inputs - define what gets included as part of the calculated hash (e.g. files, environment variables, etc.)
  • Outputs - define folders where artifacts such as files might be placed as part of the task execution; Nx makes some smart decisions based on those output locations about whether restoring by writing to the FS is required or not

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.

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

nx.json
1{ 2 "targetDefaults": { 3 "build": { 4 "inputs": ["{projectRoot}/**/*", "!{projectRoot}/**/*.md"], 5 "outputs": ["{workspaceRoot}/dist/{projectName"] 6 } 7 } 8} 9

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?

By default the cache is stored locally in your node_modules/.cache. Cache results are stored for a week before they get deleted. You can customize the cache location in the nx.json:

nx.json
1{ 2 "cacheDirectory": "/tmp/mycache" 3} 4

Enable Remote Caching

You can enable remote caching by connecting to Nx Cloud. To connect Nx to Nx Cloud run the following command:

❯

npx nx connect

Learn more about remote caching.

Turn off or Skip the Cache

If you want to ignore the cache (both reads and writes), use the --skip-nx-cache flag:

❯

nx build header --skip-nx-cache

Alternatively if you want to disable caching for a particular task, just make sure it is not part of the cacheableOperations array in nx.json (as shown above). If you're using Nx Cloud, you might want to 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.