npm can be slow, down or return random errors if you have large deploys

npm_lazy caches packages on your local network, making things faster and more predictable

If 100 servers request the same package metadata at the same time, npm_lazy makes sure that (at most) only one request goes out to the npm registry.

No database to install, replicate or manage. Data is stored under ./db/ as JSON and tar files.

Lazy caching: When a package is requested the first time, it is cached locally. No explicit need to manage packages or replication.

Metadata is expired periodically (default: 1 hour) so that the latest versions of packages are fetched.

Here are all the ways in which npm_lazy is resilient to registry failures:

All HTTP requests are retried.

All HTTP requests are subject to a maximum fetch timeout (default: 5000 ms). If this fails, the request is retried (or failed).

Invalid responses are rejected and retried:

Tarfiles are checked against the expected shasum, and cached forever if they match; if not, they are retried.

Metadata files must parse as JSON; if not, they are retried.

Metadata files are never discarded until a newer version can be fetched successfully. If the JSON metadata is older than cacheAge (default: 1 hour), we will attempt to contact the registry first. However, if contacting the registry fails, then the old version of the metadata is sent instead. This means that even when outages occur, you can install any package that has been installed at least once before.

Added support for using a http proxy (note: not a Socks5 proxy). This can be configured either via the config file or via the http_proxy environment variable, see the config at the end for an example. Thanks @migounette! As I am not using a proxy myself, please report any issues via GH (pull requests welcome!).

Note: if you already have a proxy for npm, make sure you don't run into an issue where npm uses the proxy when accessing npm_lazy. You don't want to have npm install -> proxy -> npm_lazy -> proxy, but rather npm install -> npm_lazy -> proxy since your proxy probably doesn't know how to connect to npm_lazy. You will need to disable npm's internal proxy config, see this comment for the details.

Fixed a bug which occurred when the package file on the registry was updated by the author without bumping the version, resulting in a checksum mismatch between the cached tarfile and the metadata. Thanks @univerio!

Start by running npm cache clean so that your local npm command will request every package you want at least once from npm_lazy.

Starting with v1.2.0, npm_lazy will only return a 500 error if it does not have specific file.

To clear out the npm_lazy cache, simply remove the cache directory and restart npm_lazy. npm_lazy prints out the cache location when it starts, and it defaults to ~/.npm_lazy.

Note that only package index metadata and package tarfiles are cached; all other endpoints are just a transparently proxied (e.g. you can always run npm install for cached packages but more exotic npm endpoints will not work if the registry is down; they will simply act like their non-npm_lazy equivalents).

Also, note that if you intend to write through npm_lazy you must set cacheAge to 0 so that npm metadata is always refreshed because npm wants to know that you have the most recent package _id before it allows writing. This will still return cached data for package.json indexes needed for installation if the registry is down, but only after attempting to contact the registry (this seems like a decent, but not perfect compromise).

Restarting npm_lazy will clear the package.json metadata refresh timeout and the max retries counter. All cached entries, including package.json files and tarfiles are kept, so you can safely restart the server to expire the metadata cacheAge while retaining all cached artifacts.

npm_lazy works by rewriting the download URLs for package.json results, so old files from npm shrinkwrap may interfere with it since they may contain direct references to registry.npmjs.org. Make sure you clean up that stuff.

If you are using self-signed certs, set rejectUnauthorized to false in the config.