npm-mirror / pull-through cache

This host proxies and caches package installs from registry.npmjs.org. Point npm, yarn, or pnpm here to speed up installs and cut outbound rate-limit hits. Replace mirror.example.com below with this server's actual hostname.

01 — GLOBAL NPM CONFIG

Set the registry for your user

Point the npm CLI at the mirror. This writes to your user-level ~/.npmrc and applies to every project unless overridden.

shell

npm config set registry https://mirror.example.com/

# confirm it took
npm config get registry

To go back to the public registry later: npm config set registry https://registry.npmjs.org/

02 — PER-PROJECT (RECOMMENDED)

.npmrc in the repo root

Scope the mirror to a single project instead of your whole machine — safer for teams and reproducible in CI.

.npmrc

registry=https://mirror.example.com/
# scoped packages can point elsewhere if needed:
@yourscope:registry=https://mirror.example.com/

Commit this file so every teammate and CI job resolves packages through the mirror automatically.

03 — YARN / PNPM

shell

yarn config set registry https://mirror.example.com/

.yarnrc.yml

npmRegistryServer: "https://mirror.example.com"

.npmrc

registry=https://mirror.example.com/

04 — CI/CD

Environment variable override

No repo changes needed — set this in your pipeline's environment and every npm/yarn/pnpm call picks it up.

shell

export NPM_CONFIG_REGISTRY=https://mirror.example.com/

05 — VERIFY

Confirm installs are going through the mirror

shell

npm config get registry
curl -s https://mirror.example.com/-/ping -o /dev/null -w "%{http_code}\n"

# install something and time it
time npm install lodash --no-save

Check	Expected result
`npm config get registry`	Prints `https://mirror.example.com/`
`GET /-/ping`	`200` — mirror is reachable
First install of a package	Slower — cache miss, fetched from upstream and stored
Repeat install	Fast — served from local cache/tarball store

06 — NOTES

Pull-through, not a full copy. This mirror caches package tarballs and metadata as they're requested — it doesn't proactively sync the entire npm registry. The first install of any given package/version is still fetched from registry.npmjs.org.

npm publish still goes straight to the real registry (or wherever your publishConfig points) — this mirror only accelerates installs. If it's served over plain HTTP internally, use strict-ssl=false only on trusted internal networks, or terminate TLS in front of it.