When the Registry Blinks: A Fallback Loader for UK Builds

Every UK dev team has a version of this story. It is 16:40 on a Thursday, the release candidate is green, and the package registry decides to have a moment. Installs hang. CI agents retry. Someone says the phrase that has ruined more evenings than any outage: it is probably just us. It is not just you. The default npm registry is a single point of failure for a lot of small teams, and a two-person outfit in Leeds or Bristol does not need a platform team to survive it. You need a boring fallback.

Start with the lockfile, not the heroics

The first line of defence is not a clever script. It is discipline. Commit the lockfile. Use npm ci or pnpm install --frozen-lockfile in CI. No floating ranges on the build box. If your lockfile says a tarball came from a particular URL and integrity hash, the loader can reason about it. If your build resolves fresh versions every time, you are asking a remote service to make decisions for you at the worst moment. That is not resilience; it is hope with a YAML file.

Pin your registry in .npmrc as well. A project-level config beats a developer's laptop habit. Keep the default for day-to-day work if you like, but make the fallback explicit and reviewable.

Vendor the weird ones

You do not need to vendor every package. You need to vendor the ones that hurt. Private packages, patched forks, anything with a postinstall step that reaches out to a third party, and the handful of dependencies that always seem to be at the centre of an incident. Store tarballs in a vendor/ directory or an internal object store. Record the integrity hash. Add a tiny manifest that maps package name and version to the file. This is not glamorous. It is also the difference between a bad afternoon and a lost release.

For the rest, a local mirror is enough. Verdaccio is the obvious choice for a small team. Run it on a small VM, point CI at it, and let it cache what you actually use. Do not try to mirror the whole world. Cache on demand, keep a retention window, and back up the storage. A mirror is not a compliance project. It is a speed bump for the internet.

The loader: small, explicit, switchable

The fallback loader should be the least clever part of your build. It reads a list of sources, tries the primary, then the mirror, then the vendored directory, and fails with a useful message. It should not rewrite your CI pipeline. It should sit where your package manager already looks.

One pattern that works: a small Node script that writes a temporary .npmrc, sets npm_config_registry, and shells out to the existing install command. Another is a wrapper around npm ci that swaps the registry config and retries once on a network-class error. Keep the retry budget low. A registry outage is not a reason to hammer the same endpoint forty times. Two attempts with a short backoff is enough for a human to read the log.

Pseudo-code, because the real thing should fit on one screen:

• read REGISTRY_PRIMARY, REGISTRY_MIRROR, VENDOR_DIR
• try primary with a 30-second timeout
• on failure, try mirror
• on failure, resolve vendored tarballs by name and version
• if all fail, print the package, the version and the sources tried

No daemon. No dashboard. No new service to page someone about. The loader should be boring enough that you can test it on a laptop while the kettle boils.

Prove it before you need it

A fallback you have never used is a rumour. Add a test job that runs monthly, or before every release, with the primary registry blocked. Use a hosts-file entry or a firewall rule in CI. Run the same install command. If the build succeeds from the mirror and the vendored set, you have a fallback. If it fails, you have a document.

Test the partial case too: primary down, mirror up, one private package missing from the mirror. That is the realistic failure. The loader should fall through to vendor/ for that package and keep going. Log which source won. Future you will want to know.

Finally, write the runbook in the repo. Not in a wiki nobody opens. Three paragraphs: how to trigger the fallback, how to refresh the mirror, how to add a vendored tarball. That is the whole resilience programme. It will not make the registry more reliable. It will make your Thursday less dramatic.