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.
- 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
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
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 testMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
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.