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>

This setup requires Nx 20.8 or later. Use the same pinned Nx version locally and in CI.

On an older version? Share your need for older Nx support.

Replacing @nx/s3-cache, @nx/gcs-cache, @nx/azure-cache, or @nx/shared-fs-cache? Follow the deprecated Nx cache package migration guide.

Use a read-write token and a cacheable build target. Clear the local cache before the first run so Nx can populate or reuse the remote cache, then clear it again:

npx nx reset --only-cache
npx nx build my-app
npx nx reset --only-cache

Delete that target's declared output directory, then rerun with the same source, dependencies, and environment:

npx nx build my-app

Confirm Nx reports [remote cache] and restores the output files without executing the target. A second run with a warm local cache does not prove a remote hit. Keep caching enabled during this check; skip-cache flags prevent the remote lookup.

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.

• Nx 20.8 or later, which includes the native self-hosted remote cache API.
• Pin the same Nx version for every developer and CI runner. Different versions can produce different task hashes and prevent cache sharing.
• 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.

Follow the GitHub Actions recipe or choose another provider in CI setup. Choose access based on which builds you trust, as described in tokens and access control. Using Lerna on top of Nx? See the Lerna page.