How npm caching works
npm resolves a dependency in two steps. It first fetches the package document, a JSON file listing every published version, then downloads the tarball for the version your lockfile asks for. Cacheport caches both, with different rules: package documents are refreshed every few minutes so new releases show up, while tarballs never change once published and are kept for good.
Because the tarballs Cacheport serves are byte-for-byte the ones npm published, the integrity hashes in package-lock.json still match. npm verifies every download against them, so the cache cannot hand you a package that differs from what you locked.
- Package documents
- Refreshed every 5 minutes by default. If the upstream is unreachable, the last good copy keeps serving.
- Tarballs
- Stored once per version and served from the region closest to the runner.
- Scoped and private packages
- Proxied from the private upstream you configure, never mixed with public names.
- Audit and advisory calls
- Passed through to the upstream untouched, so npm audit reports stay current.
Set it up
Project .npmrc
# Send every request through your Cacheport workspace
registry=https://acme.cacheport.cc/npm/
//acme.cacheport.cc/npm/:_authToken=${CACHEPORT_TOKEN}Or set it from the command line
# Writes the same two lines to the user-level ~/.npmrc
npm config set registry https://acme.cacheport.cc/npm/
npm config set //acme.cacheport.cc/npm/:_authToken "$CACHEPORT_TOKEN"
npm ciKeep ${CACHEPORT_TOKEN} as a literal in the file. npm expands it from the environment at install time, so the token lives in your CI secrets and never 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
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
registry-url: https://acme.cacheport.cc/npm/
- run: npm ci
env:
NODE_AUTH_TOKEN: ${{ secrets.CACHEPORT_TOKEN }}
- run: npm testMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
test:
image: node:22
before_script:
- echo "registry=https://acme.cacheport.cc/npm/" > .npmrc
- echo "//acme.cacheport.cc/npm/:_authToken=${CACHEPORT_TOKEN}" >> .npmrc
script:
- npm ci
- npm testMore for GitLab CI: GitLab CI setup guide.
CircleCI
version: 2.1
jobs:
test:
docker:
- image: cimg/node:22.11
steps:
- checkout
- run: |
echo "registry=https://acme.cacheport.cc/npm/" > .npmrc
echo "//acme.cacheport.cc/npm/:_authToken=${CACHEPORT_TOKEN}" >> .npmrc
- run: npm ci
- run: npm test
workflows:
main:
jobs: [test]More for CircleCI: CircleCI setup guide.
Jenkins
pipeline {
agent { docker { image 'node:22' } }
environment {
NPM_CONFIG_REGISTRY = 'https://acme.cacheport.cc/npm/'
CACHEPORT_TOKEN = credentials('cacheport-token')
}
stages {
stage('Install') {
steps {
sh 'echo "//acme.cacheport.cc/npm/:_authToken=${CACHEPORT_TOKEN}" > .npmrc'
sh 'npm ci'
}
}
}
}More for Jenkins: Jenkins setup guide.
Lockfiles do not need rewriting
A package-lock.json created against the public registry stores resolved URLs on registry.npmjs.org. Since npm 9, the replace-registry-host setting defaults to npmjs, which means npm swaps that host for your configured registry when it installs. You can commit lockfiles from a laptop that talks to npmjs.org directly and CI will still fetch everything through Cacheport.
Lockfiles that already point at another registry host are left alone by npm. Regenerate them once, or set replace-registry-host=always.
Release cooldown
Most malicious npm releases are found and pulled within hours. Cacheport can hold back versions younger than a set age, so a fresh install picks the newest version that has been public for, say, 24 hours. Builds with a lockfile are unaffected unless they ask for a held version, in which case the pull log shows COOLDOWN and tells you when it will be released.
Combine with the runner cache
Cacheport and your CI provider's own cache solve different problems. The runner cache restores ~/.npm on a machine that has seen the project before; Cacheport serves the packages that are still missing, from the same region, without touching npmjs.org. Many teams keep both: the restore step saves a few seconds, and Cacheport removes the slow and flaky tail.
Troubleshooting
Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.