cacheport

Ecosystem · JavaScript

pnpm registry cache for CI

pnpm reads the same .npmrc as npm, so pointing it at Cacheport is a two-line change. The lockfile stays valid and pnpm keeps verifying every package against its integrity hash.

CP-PNPMManifest
Upstream
registry.npmjs.org
Endpoint
https://acme.cacheport.cc/npm/
Config
.npmrc
Lockfile
pnpm-lock.yaml, integrity verified
Store
Content-addressable, can be cached per runner
Tarballs
Cached forever, immutable

How pnpm caching works

For packages from the default registry, pnpm-lock.yaml records an integrity hash but not a download URL. pnpm builds the URL from the registry in .npmrc at install time, so switching to Cacheport does not touch the lockfile.

pnpm keeps a content-addressable store on disk and hard-links packages into node_modules. On a fresh runner that store is empty; Cacheport fills it from a nearby cache instead of from the public registry.

What gets cached
Package metadata
Refreshed every 5 minutes, last good copy on upstream failure.
Tarballs
Shared with npm and Yarn jobs in the same workspace.
Store misses
Anything the restored store lacks is fetched from the regional cache.

Set it up

Project .npmrc

.npmrc
registry=https://acme.cacheport.cc/npm/
//acme.cacheport.cc/npm/:_authToken=${CACHEPORT_TOKEN}

The token stays a literal ${CACHEPORT_TOKEN} in the file and is read from the environment, so it never lands in the repository.

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:
      CACHEPORT_TOKEN: ${{ secrets.CACHEPORT_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

.gitlab-ci.yml
test:
  image: node:22
  before_script:
    - corepack enable
    - pnpm config set store-dir .pnpm-store
  script:
    - pnpm install --frozen-lockfile
    - pnpm test
  cache:
    key:
      files: [pnpm-lock.yaml]
    paths: [.pnpm-store]

More for GitLab CI: GitLab CI setup guide.

Store cache and registry cache together

The cache: pnpm option in actions/setup-node restores the pnpm store keyed on the lockfile. When the lockfile changes, that key misses and pnpm downloads everything again. With Cacheport behind it, those downloads come from your region in milliseconds instead of from the public registry.

Troubleshooting

Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.

Questions

Does pnpm need its own endpoint?

No. It uses the npm endpoint and shares the cache with npm and Yarn.

Do workspaces and catalogs work?

Yes. Those are resolved locally by pnpm; only the downloads go through Cacheport.

What about pnpm dlx and pnpm create?

They read the same .npmrc, so one-off tools come from the cache too.

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.