DEV Community

Roberto Hernández for One Beyond

Posted on • Updated on


Different approaches to testing your own packages locally: Verdaccio

This is part of a series of articles:

  1. Linking local files
  2. npm link
  3. npm yalc
  4. Verdaccio
  5. Relative deps

In this series, we are going to see how we can use Verdaccio to test your packages locally.

1. What is Verdaccio?

Verdaccio is, apart from a green color popular in late medieval Italy for fresco painting (method of painting water-based pigments on freshly applied plaster, usually on wall surfaces), a lightweight proxy and private packages registry.

It can be configured as required and comes out of the box with its own tiny database and introduces caching the downloaded modules along the way, so you don't need your own one to get started.

In addition, it allows you to host private Node Packages and is compatible with all client package managers (such npm, yarn and pnpm).

For those who are looking for extending their storage capabilities, Verdaccio supports various community-made plugins to hook into services such as Amazon's S3, Google Cloud Storage or create your own plugin and also provides Docker and Kubernetes support.

2. How to use it locally?

Let’s say that you have a React application and a components library and you want to test that fancy component library in the React application. On the previous post related to this series, we have seen how to develop your components library using Linking local files, Npm link and Npm Yalc

Now, we will learn how we can do it using Verdaccio.

The usual method would be uploading your library to npm or a similar package manager, then download and install the dependency. But you do not want to add the library yet because you want to test it deeper.

Verdaccio offers you a solution for that. You can install it on your local machine and use it as the provider of your library.

Let’s see how we can start using Verdaccio locally. The most straightforward method to start using it is:


To install it globally in your local machine, you just need to run the following command:

npm install --global verdaccio
Enter fullscreen mode Exit fullscreen mode


By default, Verdaccio provides you with everything to start working with the package registry. In case you want to see the default config, here you have it:

storage: ./storage 
 file: ./htpasswd 
 access: $all 
 publish: $authenticated 
 proxy: npmjs 
 proxy: npmjs 
log: { type: stdout, format: pretty, level: http } 
Enter fullscreen mode Exit fullscreen mode

For further configuration, I recommend you to check out the official documentation here.


In order to run the Verdaccio service, you just need to run the command verdaccio in the terminal. After a few seconds, you will have your fully working Verdaccio over http://localhost:4873/


Once we have the Verdaccio package registry running, we just need to follow a few steps to have our library installed on it.

First step: create the .npmrc file

We have to do that in both the library and the React application that will consume the components library in order to connect to the right package registry when we run the install command.

This should be the content of that file:

Enter fullscreen mode Exit fullscreen mode

Second step: Log in on Verdaccio package registry

Once we have the Verdaccio running, we need to create a user to be able to publish the package. We will do that by using this following command:

npm adduser --registry http://localhost:4873 
Enter fullscreen mode Exit fullscreen mode

It will ask you the username, password and email. After that, the system will log you automatically as the user that you have created.

In case that you want to create more than one user and change the session, you can use this command:

npm login --registry http://localhost:4873 
Enter fullscreen mode Exit fullscreen mode

Third step: publish your package

For publishing the library on the right package registry, you have to make sure that you have created the .npmrc pointing to the Verdaccio local url.

I will provide you with a few scripts that you have to add in the package.json of your component library in order to publish the library and upgrade the version every time you publish it. If you don’t upgrade the version every time you publish, you will return an error after running the commands.

"unpublish-library": "npm unpublish @ks/my-fancy-library --force", 
"update-version": "npm version patch --force", 
"publish-library": "npm run build && npm run update-version && npm run unpublish-library && npm publish".
Enter fullscreen mode Exit fullscreen mode

After running the command publish-library, you should be able to see see something like that on the Verdaccio dashboard:


Last step: install the library in your app, update the library and see you change.

This is the time of truth. Once we have the library published, we will install it on our React application and use a single component to see how it works.

With the Verdaccio package registry running, we will install the library via your package manager (let’s use for instance npm) and run this command:

npm install @ks/my-fancy-library@latest 
Enter fullscreen mode Exit fullscreen mode

Once you have the library installed, make sure that It s properly configured and is displaying the component that you want
After that, we are going to go to the library and we will change something on the component that you are displaying, and then you just need to do two things:

  • Build and publish your library to Verdaccio:
npm run publish-library
Enter fullscreen mode Exit fullscreen mode
  • Go to the React app and install the latest version of the component library:
 npm install @ks/my-fancy-library@latest 
Enter fullscreen mode Exit fullscreen mode

When the process finishes, you will be able to see the change you have done on the component library into your React application

Extra mile: How to run Verdaccio using docker?

There is a way to install the Verdaccio package registry using docker.It is also quite straightforward:

You need to have a docker daemon installed and running in order to run the command and raise the container.

After that you can take advantage of this command to do it:

docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio 
Enter fullscreen mode Exit fullscreen mode

If everything goes well, you should have a running Verdaccio here

Having that working, you need to follow the same instructions I mentioned above on the section which explains how to install the library locally,specifically in the configuration step because the process is almost the same. The only thing you just need to replace is the url in the .npmrc from this http://localhost:4873/ to this

Possible usages

I will leave you here a few ideas of what you can use Verdaccio for:

  • Create your own private package registry

  • Reduce the CI process time caching the packages

  • Testing monorepos and the deployment in the registry

  • As a backup for packages during the CI process.

  • Personal usage, when you have different packages related from each other's.

  • Teacher purposes (Sometimes npm mark packages as spam)

  • It allows you to use AWS or Google cloud to store the packages cache

  • Uplinks: You can configure it to define the proxy that you want to user in each package.

Interesting links

Top comments (1)

inigomarquinez profile image
Íñigo Marquínez

Nice article!