Verdaccio is a local npm registry written in Node.js. A registry is a repository for npm packages that implements the CommonJS and Semver (semanting versioning) specifications for reading package information and encoding the nature of changes between releases in the version string.

More specifically, Verdaccio acts like a local proxy sever that proxies the requests to a local cache and if the requested package is not present automatically redirects them to the official npm registry. The private repository is maintained into a single folder called storage. In addition, Verdaccio also implements its own version of some commands of the npm CLI such as npm login, npm adduser and npm publish in order to enable the creation of local private packages.

Verdaccio also supports scoped packages. Scopes are used to group related packages by creating a namespace, i.e. a sort of domain to which the related packages belong. A scoped package name begins with @ and the scope is everything in between the @ and the / characters, namely:

@scope-name/project-name



Deploying Verdaccio

As I previously mentioned in this article, Verdaccio is a NOde.js application, so you can install it globally on your server using npm:

sudo npm install -g verdaccio

To start the server and get your private registry running you have to simply type verdaccio at the shell prompt. This will fire up an instance of Verdaccio that by default will listen to the port 4873. In a production environment you also have to make sure that your application restarts if your server crashes for some reason. Here at Anywhere, we use pm2 as process manager and production runtime for Node.js applicatons. To manage Verdaccio with pm2, just follow these steps:

# install pm2 globally
sudo npm install -g pm2

# start verdaccio using pm2
pm2 start /usr/bin/verdaccio

Please observe that the path /usr/bin/verdaccio is a soft link to the executable file whose real installation path is /usr/lib/node_modules/verdaccio/bin/verdaccio.

Now that the server is up and running, you may want to make your npm client to point to your private registry server. Assuming that your Verdaccio server is running on localhost, this is done by running the following command:

npm set registry http://localhost:4873/

Moreover, if you want to use a secure connection on HTTPS you must also set up the CA certificate using the following command:

npm set ca null

Setting the ca value to null will force the client to use the CA’s trusted by your operating system. Otherwise you may specify the CA signing certificate as follows:

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

The certificate should be in PEM format with the newlines replaced by the \n character. Alternatively, you can provide a path to the certificate by executing the following command:

npm set cafile /path/to/certificate.pem

The npm set commands above will save the configuration to your ~/.npmrc file, so you can also manually edit this file with your configuration. Before starting Verdaccio you have to edit the configuration file and specify the host name or IP address and the listening port. By default, the configuration is stored in ~/.config/verdaccio/config.yaml. Edit the file and append to the bottom the following configuration:

web:
  enable: true
  title: verdaccio

listen:
  - http://0.0.0.0:4873

Observe that it is important to specify 0.0.0.0 instead of localhost, otherwise Verdaccio Web UI will not be loaded. Once you have correctly configured Verdaccio, you can start the server and type http://localhost:4873 in your browser, you will be redirected to the Verdaccio landing page that is shown in Fig. 1.



Fig. 1: Verdaccio landing page

In a corporate environment you might want to run your Verdaccio instance behind a proxy server. To do that, you must set a X-Forwarded-For header using the following properties in the configuration file:

http_proxy: http://your-proxy-url/
https_proxy: https://your-proxy-url/

You might also want to specify domain extensions proxy should not used for. This can be accomplished using the no_proxy property followed by a comma-separated list of domain extensions:

no_proxy: localhost, 127.0.0.1

Recall that you have to restart Verdaccio to make the changes on hte configuration file effective. If you have pm2 installed, you can run the following command:

pm2 restart verdaccio



Registering a new user

If you observe the screenshot of Fig. 1, you can see that in the landing page are shown the commands you have to run in order to register a new user and to publish a new package in your private registry. Execute the first command:

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

Then follow the instruction that are prompted by the system and are depicted in Fig. 2.

Fig. 2: User configuration

As a result of this operation a file htpasswd which is used to store user name and credentials is created in the folder ~/.config/verdaccio/.

Creating a private npm package

In a new folder create a new package by executing npm init and answer the questions prompted by the system leaving the defaults. Just give a package description, add your name as author and keep the entry point at index.js. The result is a package.json file with the new package information. Afterwords, create a simple index.js file that simply exports a hiVerdaccio function like so:

//  index.js
function hiVerdaccio () {
  return 'hi Verdaccio'
}

module.exports = hiVerdaccio

Next you have to publush your newly created package; to do so you have to login to your registry first by executing npm login and inputting your login credentials at the prompt. Finally, in your project root just run npm publish. When refreshing the browser you will see that the landing page has changed and will reflect the new registry status as depicted in Fig. 3.

Fig. 3: Registry status after registring a new package

Recall that your registry is simply a directory. The path to your registry can be defined in the config.yaml configuration file. By default the registry is created in ~/.config/verdaccio/storage.

Finally, Verdaccio can be configured so that a publisher can publish packages even ifan uplink is down. This can be accomplished by adding the following lines to the configuration file:

publish:
  allow_offline: true



Using a private package

Now that we have successfully registered our private package, let’s create an application that consumes it. Create a demo folder and initialise a new project by running npm init. Then, install the example package by following the standard npm process:

npm install --save example

This will install your package in the node_modules folder and update the dependency section of you package.json file. In order to test your package you have to create a new index.js file in the demo folder where you use the example package; for example:

const hiVerdaccio = require ('example')  

console.log(hiVerdaccio ())

When you run your app by executing node index.js you should see on your standard output the message hi Verdaccio.

Requesting a public package

The same process described in the previous section also applies to public packages. You just need to run npm install package-name and every dependency will be installed in the node_modules folder (either globally or locally depending on the install options specified).

Under the hood, Verdaccio looks into its storage folder to check whether the requested package has been previously cached or not. If not, Verdaccio will forward the request to the official npm registry, download the requested package, store it locally and reply to your request. The next time you need to install the same package, Verdaccio will fetch it from its local cache and serve it to you, no matter if the official registry is not reachable for whatever reason. If a package needs to be updated, Vedaccio will download the updates and update its local cache.

Conclusion

Verdaccio allows a developer to keep his own private registry with cached packages. This allows accessing your private registry also when you are off line. In addition, Verdaccio also enables the possibility to publish and maintain private packages using the standard npm client commands.