Skip to content
Source
Sign inSign up

Cache Nx and Turborepo tasks

CI / Speed and debugging

Cache Nx and Turborepo tasks

Each CI run of your monorepo builds and tests every package, also for a change to one package: an empty runner has no cached outputs. Every CI job here gets a task cache with no setup: Nx and Turborepo save the outputs of each task in the cache of the repository, and the next run takes them back.

3 min read

On GitHub Actions you need Nx Cloud, a Vercel account, or a cache server of your own for that.

No Nx or Turborepo? A package cache skips the tests of the packages that did not change.

1. Use Nx 20.8 or later, or Turborepo

The forge points both tools at its cache with their own environment variables:

  • Nx uses its self-hosted remote cache: NX_SELF_HOSTED_REMOTE_CACHE_SERVER and NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN. Nx reads them from version 20.8.
  • Turborepo uses its remote cache API: TURBO_API, TURBO_TOKEN and TURBO_TEAM.

You add nothing to your workflow, nx.json or turbo.json.

2. Push a workflow that runs your tasks

import { defineWorkflow, pullRequest, push, setup } from '@tanstack-source/ci'

export default defineWorkflow('ci', { on: [pullRequest({ branches: ['main'] }), push({ branches: ['main'] })] })
  .job('test', {
    steps: [
      setup.node(),
      setup.pnpm(),
      { name: 'Install dependencies', run: 'pnpm install --frozen-lockfile' },
      { name: 'Build and test', run: 'pnpm nx run-many -t build test' },
    ],
  })

The first run on main runs every task, and saves the outputs of each one.

3. Push a change

Push a change to one package. The tasks of the other packages come from the cache:

  • Nx shows [remote cache] next to each task that it took from the cache.
  • Turborepo shows cache hit, replaying logs for each task that it took from the cache.

Done

The tasks run only for what changed. The outputs of a task on main come back in the runs of later commits and pull requests, with no account and no secret.

Who reads which entries

The task cache uses the cache scopes of cache():

  • A run on main saves entries that every run reads.
  • A run of a pull request from a fork reads the entries of main. It saves its own entries in the scope of its pull request. No run on main or on another branch reads them. So a fork can never put its own build outputs into a trusted run.
  • An untrusted run without a pull request has no scope to write to. It reads entries, and saves none. Nx and Turborepo skip the save and go on, and the task does not fail.
  • A hidden workflow reads entries, and saves none.

No token enters the job. The token that the tools send is a fixed word, tss-task-cache. The forge knows the job from the container that sent the request.

When your job uses its own remote cache

  • Nx Cloud wins. When NX_CLOUD_ACCESS_TOKEN is set, or nx.json has nxCloudId, Nx uses Nx Cloud and ignores the task cache.
  • Your own variables win. A job can set one of the variables of a tool itself: in the env of the workflow or of the job, with a secret, or with a CI variable. Then that tool gets none of the variables of the forge. For example, a job with a TURBO_TOKEN secret for Vercel keeps its Vercel cache.

Turn the task cache off

Set taskCache: false on the job. The job then gets none of the variables:

.job('test', {
  taskCache: false,
  steps: [setup.node(), setup.pnpm(), { name: 'Install dependencies', run: 'pnpm install --frozen-lockfile' }],
})

See and delete the entries

The entries are CI cache entries. Their keys are nx-<hash> and turbo-<hash>:

src cache list -k nx-
src cache list -k turbo-

To delete them, run src ci cache delete --key <key> or src ci cache delete --all, or use Settings > CI > Cache.

  • The entries count in the 50 GB of cache of the repository. When the cache is full, the least recently used entries go first.
  • One entry is at most 5 GiB.
  • A save that the cache refuses never fails a task.