How Yarn caching works
Yarn Berry (version 2 and later) does not store registry URLs in yarn.lock. Each entry records a resolution like lodash@npm:4.17.21 and a checksum, and the registry comes from .yarnrc.yml. Changing npmRegistryServer is enough to route every install through Cacheport.
Yarn 1 is different: its lockfile keeps the full tarball URL for every package. If those URLs point at registry.yarnpkg.com, Yarn 1 will keep fetching from there. Reinstall once with the new registry set, or replace the host in yarn.lock, and commit the result.
- Package metadata
- Refreshed every 5 minutes, last good copy served if the upstream fails.
- Tarballs
- Stored once per version, shared with npm and pnpm in the same workspace.
- Private scopes
- Served from the private upstream you add, configured per scope in .yarnrc.yml.
Set it up
Yarn Berry: .yarnrc.yml
npmRegistryServer: "https://acme.cacheport.cc/npm/"
npmAlwaysAuth: true
npmAuthToken: "${CACHEPORT_TOKEN}"Yarn 1: .npmrc
registry=https://acme.cacheport.cc/npm/
//acme.cacheport.cc/npm/:_authToken=${CACHEPORT_TOKEN}Yarn Berry expands ${CACHEPORT_TOKEN} from the environment when it reads .yarnrc.yml. Every setting can also be passed as an environment variable with the YARN_ prefix, which is handy in CI.
Use it in CI
Store the token as a secret named CACHEPORT_TOKEN, then pick your provider.
GitHub Actions
jobs:
test:
runs-on: ubuntu-latest
env:
YARN_NPM_REGISTRY_SERVER: https://acme.cacheport.cc/npm/
YARN_NPM_AUTH_TOKEN: ${{ secrets.CACHEPORT_TOKEN }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: corepack enable
- run: yarn install --immutable
- run: yarn testMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
test:
image: node:22
variables:
YARN_NPM_REGISTRY_SERVER: https://acme.cacheport.cc/npm/
script:
- corepack enable
- export YARN_NPM_AUTH_TOKEN="$CACHEPORT_TOKEN"
- yarn install --immutable
- yarn testMore for GitLab CI: GitLab CI setup guide.
Zero-installs and the offline cache
Projects that commit .yarn/cache already have every tarball in the repository, so CI does not download them at all. Cacheport still helps in two places: when someone adds or upgrades a dependency, and when a branch is built before its cache files are committed. The registry setting costs nothing when it is not used.
Private scopes
Map a scope to Cacheport in .yarnrc.yml with npmScopes. Cacheport looks the scope up in the private upstream you configured for the workspace and never asks the public registry for it, so a private name cannot be shadowed by a public package of the same name.
Troubleshooting
Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.