cacheport

Ecosystem · JavaScript

npm package cache for CI

Put Cacheport between npm and registry.npmjs.org. Your lockfile, integrity hashes and scripts stay exactly as they are; installs stop depending on the public registry being fast, reachable and in a good mood.

CP-NPMManifest
Upstream
registry.npmjs.org, plus any private registry you add
Endpoint
https://acme.cacheport.cc/npm/
Config
.npmrc or NPM_CONFIG_REGISTRY
Clients
npm 7 and later, Yarn, pnpm, Bun
Metadata TTL
5 minutes (adjustable)
Tarballs
Cached forever, immutable

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.

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

.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

shell
# 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 ci

Keep ${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

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

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

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

More for GitLab CI: GitLab CI setup guide.

CircleCI

.circleci/config.yml
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

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

Questions

Do I have to change my package.json or lockfile?

No. Only the registry setting changes. npm keeps verifying every tarball against the integrity hashes in your lockfile.

Does it work with Yarn and pnpm?

Yes. Both speak the same registry protocol and use the same endpoint. See the Yarn and pnpm pages for the exact settings.

Can I publish through Cacheport?

Cacheport is read-only for npm. Publish to npmjs.org or your private registry as you do today; new versions appear in the cache on the next metadata refresh.

What happens when registry.npmjs.org is down?

Installs keep working for every version already in your cache. Package documents are served from the last good copy and the response carries a Cache-Status header that says so.

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.