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_SERVERandNX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN. Nx reads them from version 20.8. - Turborepo uses its remote cache API:
TURBO_API,TURBO_TOKENandTURBO_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 logsfor 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
mainsaves 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 onmainor 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_TOKENis set, ornx.jsonhasnxCloudId, 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
envof 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 aTURBO_TOKENsecret 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.