cacheport

Ecosystem · JavaScript

Yarn registry cache for CI

Yarn talks the npm registry protocol, so it uses the same Cacheport endpoint as npm. Yarn Berry needs two lines in .yarnrc.yml; Yarn 1 reads the same .npmrc as npm.

CP-YARNManifest
Upstream
registry.yarnpkg.com (a mirror of registry.npmjs.org)
Endpoint
https://acme.cacheport.cc/npm/
Config
.yarnrc.yml (Berry) or .npmrc (Yarn 1)
Env vars
YARN_NPM_REGISTRY_SERVER, YARN_NPM_AUTH_TOKEN
Lockfile
yarn.lock, checksums verified by Yarn
Tarballs
Cached forever, immutable

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.

What gets cached
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

.yarnrc.yml
npmRegistryServer: "https://acme.cacheport.cc/npm/"
npmAlwaysAuth: true
npmAuthToken: "${CACHEPORT_TOKEN}"

Yarn 1: .npmrc

.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

.github/workflows/ci.yml
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 test

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

.gitlab-ci.yml
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 test

More 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.

Questions

Do I need different endpoints for Yarn and npm?

No. Both use https://acme.cacheport.cc/npm/ and share one cache, so a package pulled by an npm job is a hit for a Yarn job.

Will yarn install --immutable fail after switching?

Not with Yarn Berry, because the lockfile does not store registry URLs. With Yarn 1, update the URLs in yarn.lock once.

Does it work with Plug'n'Play?

Yes. PnP changes how packages are loaded at runtime, not how they are downloaded.

Other ecosystems people set up next

Start on the free plan

20 GB of cache, every registry, unlimited users. Upgrade when your pipelines outgrow it.