Nx remote cache setup

Set both variables in the environment Nx runs in - your shell for local builds, your CI secret store for pipeline builds:

export NX_SELF_HOSTED_REMOTE_CACHE_SERVER=https://remote.cachely.dev
export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=<your-token>

Then run a cacheable task twice: nx build my-app. The first run uploads the result; the second downloads it and reports a cache hit instead of rebuilding.

NX_SELF_HOSTED_REMOTE_CACHE_SERVER must be the bare host (https://remote.cachely.dev) with no path. Nx appends /v1/cache/<hash> itself, so adding the path yourself doubles it and every request 404s. This is the single most common setup mistake. For what the variable is and how Nx uses it, see the Nx remote cache guide.

Nx only consults the cache for targets it has been told are cacheable. Declare them once in nx.json:

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

A target with no declared outputs caches its terminal output but restores no files, which usually reads as "the cache does nothing". If your hit rate is low for a different reason, the hit-rate guide covers over-keyed inputs, environment drift, and non-deterministic outputs.

• An Nx version with self-hosted remote cache support (Nx 19+).
• Every CI runner and every developer must resolve the same Nx version. Task hashes differ across Nx versions, so a mixed-version team simply never shares cache entries - the requests succeed and every one of them misses.
• Each token is scoped to a single workspace. Issue one per CI pipeline, repo, or developer so any of them can be revoked without breaking the rest.

Wire it into your pipeline with CI setup, then give pull requests a read-only token as described in tokens and access control. Using Lerna on top of Nx? See the Lerna page.