Host, Publish and Manage Private npm Packages with Verdaccio

Verdaccio: A powerful tool for easy management of private npm packages

Core points

• Verdaccio is a free alternative to npm commercial private package hosting, publishing, and management services. It allows the creation of a local npm registry without any configuration and comes with its own database.
• Verdaccio acts as a local cache/proxy server, and when dependencies are not found in the custom repository, they are downloaded from the official npm registry and saved in the local storage folder. It also supports the creation of local private packages.
• Verdaccio is easy to install and configure and can be set to automatically restart in occasional crashes. It also allows users to register to publish packages.
• In addition to hosting private packages, Verdaccio also caches public packages. It checks whether there are requested packages in its storage folder, and if it cannot be found, forwards the request to the official npm registry to download, store and reply to the request. This means that even if the official registry goes down, the cached version is still accessible.

This article was reviewed by Panayiotis «pvgr» Velisarakos and Jurgen Van de Moere. Thanks to all SitePoint peer reviewers for making SitePoint content perfect!

As we all know, npm and its registry are the de facto JavaScript package managers and the largest collection of code in the world. But sometimes when developing amazing new packages, you need extra privacy. Whether it’s a company project (which should not be shared publicly), a master/bachelor’s thesis project, or just because you, like me, sometimes feel ashamed of your initial attempt on a new topic.

For whatever reason, there are many options. Perhaps the easiest way is to register a business service for npm and then you can start. But this requires a fee and may not be suitable for everyone's wallet.

Luckily, there is a free alternative called Verdaccio that can help you.

Introduction to Verdaccio

Verdaccio is an npm package that allows you to create a local npm registry without any configuration. This is a project with all the necessary functions, with its own database. It does this by acting as a local cache/proxy server.

This means that whenever you try to install something that doesn't exist from a custom repository, it pings the official npm registry and downloads the dependencies. Your custom repository saves these dependencies in a simple folder called storage. The next installation will use a copy of this local cache. Most importantly, some commands from the npm client, such as npm login/adduser/publish, are copied to support the creation of local private packages, which you will see later in this article.

If you think this is nothing new, already there is Sinopia, you are right. Verdaccio is just a fork of Sinopia that maintains backward compatibility, but at the same time tries to keep up with the changes in the official npm. One such change that is not available in Sinopia is the scope package, which you may have seen before using libraries like Angular 2 or TypeScript npm hosting types. You can easily identify them by the @ symbols in the preceding ones:

<code># 安装 Angular2 依赖项
npm install @angular/core

# 安装 TypeScript 的官方 Node.js 类型定义
npm install @types/node</code>

Sinopia and Verdaccio are both available on Mac/Linux and Windows.

Beginner of Verdaccio

Since Verdaccio is an npm package, you can install it simply by running the following command:

<code>npm install -g verdaccio</code>

Then calling verdaccio will start the instance and run your private registry.

By default, it will listen on port 4873. We'll discuss how to change these settings later.

In this article, we will introduce setting up the registry on your development machine. In a corporate environment, you may need to do this on a dedicated server so that it can be accessed by all developers.

Verdaccio is a Node.js application, which means you should be careful to restart it whenever you crash. I recommend using pm2. You just need to run the following steps:

<code># 安装 pm2
npm install pm2 -g

# 使用 pm2 启动 Verdaccio
pm2 start PATH-TO-GLOBAL-VERDACCIO/verdaccio
# --> 例如，对于 Windows：C:/Users/[USERNAME]/AppData/Roaming/npm/node_modules/verdaccio/bin/verdaccio</code>

In addition, if after reading this article you concluded that Verdaccio is not suitable for you, just stop the process and uninstall Verdaccio with the following command:

<code>npm uninstall -g verdaccio</code>

Configure client

When the registry is up and running, you need to point the npm client to the new address. This can be done by running the following command:

<code>npm set registry https://www.php.cn/link/0f3ea482c9513bf4548f302a46d9932d/</code>

If you just follow the steps in this article and want to restore to the original npm registry later, just run this command npm set registry https://www.php.cn/link/c0ab525d634e80fd8e20e3d6dc00b11c (For HTTPS-based access) or npm set registry https://www.php.cn/link/6baadc89159617043965f9e1889224e7 (For classic HTTP access).

In addition, if you provide registry services over HTTPS, you need to set up appropriate CA information.

<code># 将值设置为 null 将使用操作系统提供的列表
npm set ca null</code>

You can now access the registry browser by navigating to the address https://www.php.cn/link/0f3ea482c9513bf4548f302a46d9932d.

Configure custom registry

When the server starts, a new configuration file named config.yaml is automatically created. By default, it will be created in your user folder. On Windows, this might look like this:

<code>C:\Users\[USERNAME]\.config\verdaccio\config.yaml</code>

An important setting is to configure the default port for Verdaccio listening. You can change this setting by adding the following lines at the end of the configuration file.

<code># 安装 Angular2 依赖项
npm install @angular/core

# 安装 TypeScript 的官方 Node.js 类型定义
npm install @types/node</code>

Another setting of interest might be the use of a proxy, especially in a corporate environment. These settings are as follows:

<code>npm install -g verdaccio</code>

Remember, after changing any configuration, restart Verdaccio by killing the current process or stopping the pm2 process and restarting it.

Registered User

Last but not least, we need to configure a user that publishes the package to your registry. We can do this using the default adduser command, which points to our custom registry.

<code># 安装 pm2
npm install pm2 -g

# 使用 pm2 启动 Verdaccio
pm2 start PATH-TO-GLOBAL-VERDACCIO/verdaccio
# --> 例如，对于 Windows：C:/Users/[USERNAME]/AppData/Roaming/npm/node_modules/verdaccio/bin/verdaccio</code>

After that, just follow the prompts on the command line.

Remember to use the same port you configured earlier.

This user will be used to authenticate against Verdaccio instances. In addition to the config.yaml file mentioned above, you will also find a newly created htpasswd file to store your login name and credentials.

Your first private npm package

Now, we are ready to create our first private package. We will create a simple hello-world package and see the process of publishing it.

Create package

First, create a new folder called hello-world somewhere. Now, we need to start a new package, and we use the command npm init to do this. You will be asked a bunch of questions, but now, most questions accept default values. Just give it a description, keep the entry point in index.js and add your name as the author. The result is a file called package.json that describes your package.

A good practice is to prefix your package name so you can tell immediately whether you are using a private local source or an official npm source.

The next part is creating the actual package. Therefore, we create an index.js file. This simple example will only export a HelloWorld function:

<code>npm uninstall -g verdaccio</code>

Release Package

The rest is now to release your package. To do this, we first need to use npm login to log in to our registry. You will be prompted to enter the username and password you set earlier.

After completing this operation, just run npm publish in the root directory of hello-world to complete the operation.

If you now access the registry browser in your browser again, located at

https://www.php.cn/link/0f3ea482c9513bf4548f302a46d9932d/, you will see that the list contains the new package .

Sample User Application

Now that we have published our private package, let's create a simple demo application to use it.

In a new folder demo, we use npm init again to create a new node application. Again, accept all suggestions, maybe add only description and author information.

After

, create an index.js file that will act as the root directory of our application.

Installing your private package

In order to install the private package, you basically have to do the same thing as the standard npm process.

<code># 安装 Angular2 依赖项
npm install @angular/core

# 安装 TypeScript 的官方 Node.js 类型定义
npm install @types/node</code>

This installs the package into your node_modules folder and updates the dependencies section of package.json.

Now we can use the package. Open index.js and add the following code:

<code>npm install -g verdaccio</code>

Now, when you run your application using node index.js you should see Hello World as output on the command line.

Congratulations, you just posted and used your own private package!

Request a public package

Same goes for public packages. You just keep running npm install package-name and everything will be installed in the node_modules folder as usual.

What Verdaccio does behind the scenes is to check its storage folder and check if the requested package exists. If it does not exist, it will try to forward the request to the official npm registry, download and store it, and then reply to your request. The next time you make an npm install request for the same package, it will now provide the package.

So even if the official registry goes down or is inaccessible for any reason, you can still access your own cached version. Verdaccio will always download only the requested content. If you post some updates, you will download them as needed.

Please note that the registry browser should not display public packages. If you do need to display them, you can edit the .sinopia-db.json file and manually add the package name to the list array. Don't forget to restart Verdaccio afterwards.

Conclusion

So now you can host your own private registry and benefit from cached public packages. Most importantly, you can now also publish private packages without having to communicate with the cloud. After the installation is complete, all relevant npm client commands are the same as usual.

In the crazy situation where some of your packages are damaged or damaged, remember that it is just a folder store hosting your packages, so navigate there and delete the faulty package. The next installation may resolve your issue.

I hope you enjoyed this post and look forward to hearing you in the comments!

FAQs (FAQ) about using Verdaccio's Private NPM Packages

What is Verdaccio and why should I use it for my private NPM package?

Verdaccio is an open source, lightweight, and powerful private NPM registry that allows you to privately host your own NPM packages. This is a great tool for developers who want to control their code and dependencies. Verdaccio provides a safe and efficient way to manage NPM packages, allowing you to cache packages, control access, and even use them as a backup option when the primary NPM registry goes down.

How to install Verdaccio on my system?

Installing Verdaccio is very easy. You need to install Node.js and npm on your system. After the installation is complete, you can use the npm install command to install Verdaccio: npm install -g verdaccio. This will install Verdaccio globally on your system.

How to publish my private NPM package using Verdaccio?

After installing Verdaccio, you can publish your private NPM package by first logging in to your Verdaccio registry using the npm login command. You will be prompted for your username, password, and email. Once logged in, navigate to your package directory and publish your package using the npm publish command.

How do I control access to my private NPM package in Verdaccio?

Verdaccio allows you to control access to private NPM packages through its configuration file config.yaml. You can specify who can access, publish, and unpublish packages. You can also create user groups and assign permissions to them.

Can I use Verdaccio as a cache for public NPM packages?

Yes, Verdaccio can act as a proxy and cache for public NPM packages. This means that when you install the package, Verdaccio will first check if it is available in its storage. If unavailable, it will fetch it from the public NPM registry and cache it for future use.

How to configure Verdaccio to use it as a fallback option?

You can configure Verdaccio to act as a fallback option by setting it as your primary registry in the .npmrc file. This way, whenever the main NPM registry goes down, npm will automatically use Verdaccio.

Can I integrate Verdaccio with other tools?

Yes, Verdaccio can be integrated with a variety of tools such as Docker, Kubernetes, and GitLab. This makes it a universal tool that can adapt to many different development workflows.

How to migrate my package to Verdaccio?

Migrating your packages to Verdaccio is as easy as publishing them to the Verdaccio registry. You can do this by logging in to your Verdaccio registry and using the npm publish command.

Can I use Verdaccio in a team environment?

Of course. Verdaccio is designed to work in a team environment. You can control who can access which packages, making it a great tool for collaboration.

How to contribute to Verdaccio?

Verdaccio is an open source project, and contributions are welcome at any time. You can contribute by reporting errors, suggesting features, improving documentation, or submitting pull requests.

The above is the detailed content of Host, Publish and Manage Private npm Packages with Verdaccio. For more information, please follow other related articles on the PHP Chinese website!