This is part of a series of articles:
- Linking local files
- npm link
- npm yalc
- Verdaccio
- 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:
Installation
To install it globally in your local machine, you just need to run the following command:
npm install --global verdaccio
Configuration
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
auth:
htpasswd:
file: ./htpasswd
uplinks:
npmjs:
url: https://registry.npmjs.org/
packages:
"@*/*":
access: $all
publish: $authenticated
proxy: npmjs
"**":
proxy: npmjs
log: { type: stdout, format: pretty, level: http }
For further configuration, I recommend you to check out the official documentation here.
Usage
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:
@ks:registry=http://localhost:4873
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
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
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".
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
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
- Go to the React app and install the latest version of the component library:
npm install @ks/my-fancy-library@latest
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
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 http://0.0.0.0:4873/
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.
Top comments (1)
Nice article!