Configure Nx Remote Cache

What is Nx Remote Cache

Nx is a Monorepo build system with Remote Caching support that speeds up builds by caching task outputs and reusing them across different machines.

Nx includes support for TypeScript & JavaScript frontend, backend, Electron & React Native applications in Monorepo or multi-repo setups.

Notable plugins: @nx/react, @nx/angular, @nx/vue, @nx/react-native, @bennymeg/nx-electron.

Nx main concepts are Targets & Tasks, for each target Nx computes a hash of the task definition, inputs, environment, and relevant configuration, then checks Local and Remote Cache before running the work locally.

• On a Cache Miss Nx runs the task, stores the outputs, and makes them available for later builds.
• On a Cache Hit Nx quickly restores the outputs and skips the expensive work across the build graph.

BuildFetch Cache fully implements the Nx Remote Cache Specification both in Cloud & On-Prem. Nx builds can use BuildFetch as their shared Remote Cache for CI, Engineer & AI agent environments without 3rd party adapters.

Official Nx docs: "How Caching Works".

Schematic example: say a first run of nx build web misses the cache, spends time executing the tasks, and uploads the results to Nx Remote Cache:

nx build web

  Inputs
  +----------------------+
  | source files         |
  | project config       |
  | task options         |
  | env vars             |
  | ...                  |
  +----------+-----------+
             |
             v
  Compute cache keys from inputs
             |
             v
  +----------------------+
  | Nx Remote Cache      |
  | keys: a3f9...c2      |
  | status: MISS         |
  +----------+-----------+
             |
             v
  Run tasks (~10 minutes)
             |
             v
  Upload task outputs to Remote Cache

Later builds with the same or partially same inputs reuse all or most of those entries. Nx computes the cache keys, hits remote cache, and restores the outputs in seconds instead of rebuilding.

nx build web  (same inputs on another machine)

  Inputs unchanged
  source files · project config · task options · env vars
             |
             v
  Same cache key: a3f9...c2
             |
             v
  +----------------------+
  | Nx Remote Cache      |
  | key: a3f9...c2       |
  | status: HIT          |
  +----------+-----------+
             |
             v
  Downloads outputs from Remote Cache (~ few seconds)
             |
             v
  Skip ~10 minutes task run
  Build finishes much quicker.

Share Nx Cache Across Machines

For Nx outputs to be shared across machines, Nx needs to be configured with Remote Cache.

Nx Remote Caching lets teams share build outputs across engineer workstations, CI, and AI agent environments.

CI, having a more reproducible and controlled environment, typically both reads from and writes to the shared remote cache. Engineers and AI agents read those outputs without uploading new entries.

That keeps the cache warm from reproducible CI builds while reducing repeated work on other machines.

Nx reuses an output only when the task inputs and relevant configuration match. Keep project configuration, dependency graphs, environment variables, and build tool versions consistent when sharing a cache.

Instead of rerunning the same tasks on every machine, Nx restores cached outputs, which turns builds that took minutes into cached builds that finish in seconds when hit rates are high.

Cached Nx Build Example

After CI populates the Nx Remote Cache, a clean rebuild on another machine can resolve many expensive tasks from cache. In a typical scenario:

First build, where CI populates the remote cache:

$ export NX_SELF_HOSTED_REMOTE_CACHE_SERVER="https://<project-cache-url>"
$ export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN="<generated-token>"
$ nx build web

> NX  Running target build for project web
... compiling ...
Build completed in 10m 4s

Subsequent build, whether by an engineer, AI agent, or fresh CI agent, can finish in seconds:

$ export NX_SELF_HOSTED_REMOTE_CACHE_SERVER="https://<project-cache-url>"
$ export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN="<generated-token>"
$ nx build web

> NX  Retrieved outputs from remote cache
Build completed in 4s

When Nx Remote Cache helps most

Nx Remote Cache is especially valuable in ephemeral, autoscalable CI environments, where CI agents are often recreated without durable local disk state.

It also helps in actively developed Monorepos where CI continuously warms the shared Nx Remote Cache for the whole team as the codebase evolves with each commit.

Configure Nx Remote Cache

Before setting up Nx Remote Cache, ensure you have created BuildFetch Project and Token(s). Official Nx self-hosted caching documentation: https://nx.dev/docs/guides/tasks--caching/self-hosted-caching#usage-notes.

Nx Remote Cache is configured with environment variables.

BuildFetch Project Cache Setup tab will provide:

• NX_SELF_HOSTED_REMOTE_CACHE_SERVER
• NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN

Generate Tokens

We recommend generating a cache:readwrite Token for CI and cache:readonly Token(s) for developer machines.

Generally, there are two ways to manage developer Tokens:

• For simpler setups, issuing and rotating a single cache:readonly Token could be sufficient.
• For precise access control, each developer should register in BuildFetch, then issue and rotate their own individual cache:readonly Token(s).

Generating cache:readwrite Tokens requires Project/Org Admin scope.

For Open Source Projects, we recommend not storing a cache:readonly Token in publicly accessible code because it could lead to misuse and unintended exhaustion of monthly Project limits.

Configure Nx with the environment variables below before running your builds. Replace the placeholder values with the remote cache URL shown in the Project Cache Setup tab:

export NX_SELF_HOSTED_REMOTE_CACHE_SERVER="https://<project-cache-url>"
export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN="<generated-token>"

Keep the generated Token in your CI secret store or local credential environment; do not commit it to source control. If you want read-only developer access, use a cache:readonly Token in NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN.

Export these variables in the shell or CI environment used for compilation, then simply run your build through Nx. Nx logs will confirm whether the cache is active:

# Build with read-write setup to upload caches to BuildFetch.
$ nx build web
# Clean local Nx caches.
$ nx reset
# Download caches from BuildFetch skipping expensive work. 
$ nx build web