Skip to content
BoringCache

Published · Updated

Move from Nx's legacy self-hosted cache

Replace Nx’s deprecated custom task runner while preserving task hashing. Change the remote-cache connection and compare cold and warm builds before rollout.

Replace the deprecated custom task runner.

Nx’s custom task runner API is deprecated and unsupported. Use a supported remote-cache integration; for custom logic around task execution, Nx provides plugin hooks from version 20.4.

Change the remote-cache connection while preserving Nx task hashing. Nx continues to decide the task graph, inputs, outputs, and cache keys. The remote cache stores and returns the matching task outputs.

Migrate the cache connection before changing build settings.

  1. 1. Record the current behavior. Capture the Nx version, package-manager lockfile, affected targets, declared outputs, and a cold and warm run.
  2. 2. Remove the legacy runner binding. Follow the Nx migration for the version your repository uses. Do not keep two remote caches active during the comparison.
  3. 3. Connect one supported remote cache. Choose Nx Cloud, an Nx-supported self-hosted option, or BoringCache based on where the task artifacts need to be reused.
  4. 4. Start with restore-only CI. Confirm that a known task artifact restores correctly before allowing a trusted job to publish new entries.
  5. 5. Compare builds with matching inputs. Use the same commit, runner, targets, and dependency state. Check Nx cache-hit output as well as total job time.

Keep the Nx command in the repository.

The Nx adapter supplies the remote-cache endpoint and a short-lived process credential. The repository keeps the command and cache tag in .boringcache.toml, so local builds and CI use the same setup.

[adapters.nx]
tag = "nx-cache"
command = ["nx", "affected", "--target=build"]

# Run locally or in CI
boringcache nx

Choose the cache and CI features your team needs.

Nx Cloud includes broader Nx-specific CI features. BoringCache focuses on shared cache across Nx, Docker, compiler caches, other build tools, CI providers, and local development. Choose the service with the cache and CI features your team needs; do not decide from one warm-run number alone.

Start with your repository

Run boringcache onboard once. BoringCache finds useful cache state, writes .boringcache.toml, and keeps the same cache names across local builds and CI.

Open quick start Browse build tools