A lazy mirroring server for npm
JavaScript Shell
Latest commit f78fe30 May 19, 2014 @jdpaton jdpaton Merge pull request #16 from reidev/doc-fixes
Options and Documentation Fixes
Failed to load latest commit information.
bin Add licensing and copyright notices. Nov 26, 2013
config Set default access to registry server in https Apr 24, 2014
example added default config option Mar 24, 2014
.gitignore Initial commit. Nov 12, 2013
.jshintrc Cumulative v3.0.0 commit. Mar 19, 2014
.travis.yml Require node 0.10 or greater. Mar 22, 2014
CHANGELOG.md v0.3.2 Apr 25, 2014
LICENSE.txt Add licensing and copyright notices. Nov 26, 2013
README.md Correct --cache_dir flag in README Apr 29, 2014
TODO.md Dummy travis-force-build commit. Mar 22, 2014
package.json v0.3.2 Apr 25, 2014
server.js Cumulative v3.0.0 commit. Mar 19, 2014



A lazy mirroring local npm server.

Build Status


This package provides a lazy mirroring option for those that:

  • Don't want to mirror the entire couchDB for npmjs.org
  • Don't want to setup cron jobs for those tasks
  • Want to use an in-memory caching server (allocation configurable)
  • Want to easily cache dist tarballs and package metadata to disk


  • npm install -g npm-lazy-mirror


With CLI flags:

  • npm-lazy-mirror -p <port> -a <remote_address> -b <bind_address> --cache_dir /npm-data

With a JSON configuration:

  • npm-lazy-mirror -C /path/to/config,json

    See example/server-config.json for usage.

Note: Your remote_address configuration is important, as it is the address used when re-writing tarball URLs in the metadata. It's certainly always best to use a DNS entry here, rather than an IP.

Client configuration

Simply point your local npm config to the lazy mirror (permanent):

npm config set registry http://localhost:2000/

or per install:

npm i --registry http://localhost:2000 supertest


Run npm-lazy-mirror -h to see a full list of options.


  • Caches all tarball / JSON metadata to disk
  • Mirror serves files (200MB max by default) from memory, with a configurable LRU cache.
  • Ability to blacklist packages by semantic versioning specification
  • Option to serve stale resources while the upstream registry is offline
  • Upstream resources are fetched on the fly from the remote registry, the fetching, storing and serving to the client all happen in the same request.
  • Configurable with custom npm registries.
  • HTTP/S proxy support
  • It's Fast and stands up under load. Expect 5000+ req/s with one core.

A cold run installing express takes ~12 seconds (fetching from upstream registry on-the-fly):

npm install express  2.44s user 0.81s system 27% cpu 11.769 total

A warm run after all express assets are locally cached takes ~3 seconds:

npm install express  2.43s user 0.78s system 115% cpu 2.768 total

Implementation Caveats

You cannot use this mirror for publishing modules or user management, such requests will be forwarded to the upstream registry for processing.