npm private registries are your own curated, secure, and lightning-fast mirrors of the public npm registry, or even hosts for your proprietary packages. They save you from hitting the public registry for every single dependency, which speeds up builds and makes you immune to public registry outages. Think of it as having your own personal npm warehouse.
Let’s see one in action with Verdaccio, a popular lightweight private registry.
First, you need to install Verdaccio globally:
npm install -g verdaccio
Then, you start it up:
verdaccio
By default, Verdaccio runs on http://localhost:4873. Now, to use it, you need to tell your npm client to point to it. You can do this globally for your user or per-project. For global configuration:
npm config set registry http://localhost:4873
To test, you can try publishing a dummy package. Create a new directory, my-private-package, cd into it, and run:
npm init -y
echo "console.log('hello from private package');" > index.js
npm publish
If this is your first time publishing, Verdaccio will prompt you for a username, password, and email. These credentials are for Verdaccio itself, not your npmjs.org account.
Once published, you can install it in another project:
# In a different project directory
npm install my-private-package
This npm install will now hit your local Verdaccio instance instead of the public npmjs.org.
The mental model is simple: npm clients ask the configured registry for packages. If it’s the public registry, they get it from npmjs.org. If it’s your private registry (like Verdaccio), they ask your local server. Your private registry either has the package cached from a previous download from the public registry, or it fetches it from the public registry itself and then serves it to your client. This way, subsequent requests for the same package are served directly from your fast, local server.
For more advanced setups, Verdaccio’s configuration file (~/.config/verdaccio/config.yaml by default) lets you control storage locations, authentication methods (like LDAP or GitHub OAuth), upstream proxy settings, and more. Nexus Repository Manager offers a more feature-rich, enterprise-grade solution with support for multiple repository types (npm, Docker, Maven, etc.) and advanced security policies.
The key levers you control are the registry URL your npm client points to and the configuration of the registry server itself. This includes how it stores packages (local disk, S3, etc.), who can access it, and how it authenticates users.
Many people are unaware that Verdaccio, by default, caches packages downloaded from the public registry. This means that after the first successful npm install of a package, subsequent installs of that same package version will be served directly from your Verdaccio instance, even if the public registry were to go offline. This caching mechanism is what provides the speed benefits and resilience against public registry issues.
The next step is often setting up authentication to restrict who can publish and consume packages from your private registry.