How to Set Up a Private NPM Registry Locally

Setting up a local NPM registry for private packages.

In this post, we will learn about setting up NPM Registry for local development. We can also use this registry for publishing private packages. Most of the organizations and top businesses generally prefer to have their own NPM registry to store their own private javascript code and can semversion them similar to every npm package.

What is the NPM registry?

NPM registry is the database of javascript packages which comprise of software and its metadata, can also be versioned just like Git. The most common registry that open-source developers and organizations across the world use is public NPM registry but it is not the only registry we have.

A Private NPM Registry — Bit.dev as an example of what’s possible

The most popular private NPM registry for front-end developers (IMHO) is Bit.dev (it is in fact a combination of three things: A private NPM registry, a documentation site, and a CLI tool for publishing components).

Bit.dev lets you decide whether you’d like to make your packages (front end components) available for everyone or just those with the right permissions.

It also lets you choose between using NPM or Yarn to install components or (and this is the neat part) use its own CLI tool to import components. When you import a component you’re sort-of cloning it into your repository so that you can change its source code and publish it back with a bumped version.

Learn more here:

Import components | Bit

This “marriage” between a private registry and a documentation site, makes it easy for dev teams to find and reuse components across repositories.

Exploring React components published to Bit’s registry

For this article, we will be using verdaccio to set up a local NPM registry. Verdaccio is the lightweight open-source private NPM proxy registry with an active open-source community.

Why do we choose Verdaccio?

We can use other npm registries, but we choose verdaccio because of the following reasons —

1. Open Source: It is an open-source lightweight npm registry with an active development community.
2. Web Interface: It has a sleek and simple web interface, similar to a public NPM registry. It has a dark mode too.
3. Authentication: It comes up with its inbuild authentication plugin and we can also extend the type of authentication with the support of plugins.
4. Support of Plugins: It has plugin support and provides a wide range of plugins for authentication, storage, middleware and many more. We can also create custom plugins according to our requirements. That’s the beauty of Verdaccio.
5. Uplinks: It supports references to multiple backends. Here backend, we are referring to the registry. We can add as many registries as we want, and it even supports private NPM registries with auth.
6. Package Access: It’s a kind of authorization layer that provides the allow and restrict access to the packages and scoped packages, generally depending on the authorization plugin.
7. Scalability: We can scale it easily because of its plugins. It also supports Docker and Kubernetes which makes it easier to deploy and scale.

Installing Verdaccio using Docker

There are plenty of ways to install verdaccio locally. As it supports Docker so we would be using Docker to install verdaccio on our local system. With Docker, we can keep it isolated from our local environment and other dependencies. Make sure you have Docker installed and running on your local system.

Before installing verdaccio, let’s create the configuration file that it uses to set up the NPM registry. You can learn more about configuring it from its official docs. We will be using the default configuration.

./conf/config.yaml

Create a new separate directory and save the above configuration in conf/config.yaml file.

mkdir verdaccio && cd verdaccio
mkdir conf
# Create a new file and save the above configuration
touch conf/config.yaml

Let’s create storage and plugins directories which we will mount as a docker volume.

mkdir storage
mkdir plugins

With all these things in place, our directory structure will be similar to —

./verdaccio
├── conf
│   └── config.yaml
├── plugins
└── storage

Let’s set up our own NPM registry simply by running the Docker command —

docker run -it --detach \
    --publish 4873:4873 \
    --volume `pwd`/conf:/verdaccio/conf \
    --volume `pwd`/storage:/verdaccio/storage \
    --volume `pwd`/plugins:/verdaccio/plugins \
    --name verdaccio \
    verdaccio/verdaccio

Verdaccio by default runs on 4873 port so we have published the same port on our host machine, but as it’s running inside docker, we can publish any port on our local machine unless it is not bound to some other application. Moreover, we can change the listening port of verdaccio by passing an environment variable VERDACCIO_PORT=<DESIRED_PORT> .

Let’s check whether our docker container is running or not —

docker ps

The output would be something similar to this —

docker ps

Awesome!!! Our local NPM registry is up and running, so let’s open it in the browser atlocalhost:4873 and publish a dummy npm package on it.

Verdaccio

We can see the Verdaccio up and running in a beautiful dark mode UI theme. Let’s follow the command shown on the dashboard to create the user and publish our dummy package.

Verdaccio default configuration uses htpasswd authentication plugin but we can use other plugins like LDAP, Bitbucket, Gitlab, GitHub and many more.

Let’s create a new user by running the following commands —

npm adduser --registry http://localhost:4873

It will ask you to enter a username, password and public email address. Let’s login in to the UI with the same credentials that we have provided here. Let’s publish our dummy NPM package on our local registry.

Publishing NPM package

In the same verdaccio directory, let's create another directory named helloworld —

mkdir helloworld
cd helloworld

Let’s see the package.json for the project —

{
  "name": "@mypackage/helloworld",
  "version": "1.0.0",
  "description": "helloworld dummy project",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "Ankit Jain",
  "license": "ISC"
}

Let’s publish this as scoped package named @mypackage/helloworld by running the following command —

npm publish --registry http://localhost:4873

We can see an output as shown below —

npm publish — registry http://localhost:4873

Let’s browse our NPM local registry and check the dashboard. We can see our published package and can also download it from there like any other public NPM registry.

mypackage/helloworld

The final directory structure after publishing our package —

./verdaccio
├── conf
│   ├── config.yaml
│   └── htpasswd
├── helloworld
│   └── package.json
├── plugins
└── storage
    └── @mypackage
        └── helloworld
            ├── helloworld-1.0.0.tgz
            └── package.json

Conclusion

In this article, we have learnt about setting up the NPM registry locally and why did we choose verdaccio for it. In my previous article “Install NPM Private Packages in CI/CD with GitHub Actions”, I explained how we can use our private/local registry to install packages using .npmrc configuration files and how we can use our local/own NPM registry with CI/CD pipelines. We can similarly deploy this NPM registry in production by using Nginx Reverse Proxy with SSL.

Feel free to comment and ask me anything. You can follow me on Twitter and Medium. Thanks for reading! 👍

Build Apps with reusable components, just like Lego

Bit’s open-source tool help 250,000+ devs to build apps with components.

Turn any UI, feature, or page into a reusable component — and share it across your applications. It’s easier to collaborate and build faster.

→ Learn more

Split apps into components to make app development easier, and enjoy the best experience for the workflows you want:

→ Micro-Frontends

→ Design System

→ Code-Sharing and reuse

→ Monorepo

Learn More

How We Build Micro Frontends

How we Build a Component Design System

How to reuse React components across your projects

5 Ways to Build a React Monorepo

How to Create a Composable React App with Bit

Code Principles Every Programmer Should Follow

Tools for Consistent JavaScript Code Style

13 Top Serverless Solutions for 2020