Testing your npm package before releasing it using Verdaccio + ngrok

Making sure that your npm package works as expected after publishing on npm can be a nightmare. Since it can have several different working environments, it may behave differently on your machine than on a server. Actually, fixing a bug involves publishing again your package thus bumping up its version number.

Here at Strapi, we faced this situation a lot. So, we set up a private npm local registry with Verdaccio and ngrok to test our package on a server before releasing it on npm.

In this post, we’re going to explain how to create a public npm registry dedicated for testing your npm package on both your machines and servers before releasing it officially.

Set up your private npm local registry

This first step will allow you to publish a package on your private local registry and not on the npm registry itself. It means that rather than installing your package from npm itself you it will be downloaded from your private local registry if it exists. If not it will take the one from the official npm registry (https://registry.npmjs.com).

Setup

To create your private npm repository server, you have to install Verdaccio: a private npm repository server.

npm install -g verdaccio

Next, start the server.

verdaccio

ℹ️ You should be able to see the interface at the following address http://localhost:4873.

Update default registry

Then we set http://localhost:4873 as default registry.

npm config set registry http://localhost:4873

Add a new user

Verdaccio automatically creates a configuration file but doesn’t register the first user for you. Run the following command to create a new user on the private local registry.

npm adduser

Use, for example, the following credentials:

• Username: test
• Password: test
• Email: test@company.com

Create a package

We are going to create a very simple package so we can publish it later. First of all, create an empty folder on our machine.

cd /path/to/a/sandbox/folder mkdir foo-package cd foo-package

Secondly, initialize your package by creating a basic package.json file.

npm init

After answering with default responses (press Enter for each question), the package.json file should look like the following:

{
  "name": "foo-package",
  "version": "1.0.0",
  "description": "Basic package to test publication",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "MIT"
}

Finally, create an index.js file which contains the logic of your package.

module.exports = () => {  
  console.log('My package does nothing!');
};

Publishing the package locally

The package is ready to be published on your private local registry. To publish it, nothing more simple than running the following command at the root of the package.

npm publish

For Mac OS users, you can look for your package at /Users/xxx/.config/verdaccio/storage and ensure it has been successfully published.

Now that your package is published on our ‘test’ registry (http://localhost:4873), only you can access and download it. In order to test it on another machines or servers, you need to expose it to others…

Make the private local registry public

Right now, your private local registry is only accessible on your machine at http://localhost:4873. We’ll use ngrok to share it with collaborators.

Install ngrok

Open a new tab or window in your terminal, and install ngrok through npm:

npm i ngrok -g

Then, run this command to expose the 4873 port:

ngrok http 4873

It should create a URL like this http://e55ba6a3.ngrok.io. Open it in your browser, and you will see your own npm registry. Your registry is now accessible by everyone you shared the URL with.

Use your public npm registry

At Strapi, before releasing a new version we always test our package in real production environment. We launch an Ubuntu server on AWS with Node.js, npm and git pre-installed.

Run this command to use your public npm registry.

npm set registry http://e55ba6a3.ngrok.io

ℹ️ Do not forget to use your own ngrok URL.

Finally, install your package on the server.

npm install foo-package

By running this command, npm will try to install the package from your registry first (http://e55ba6a3.ngrok.io -> http://localhost:4873). But, if there is no corresponding package it will use the one from the official registry (https://registry.npmjs.com).

Conclusion

We hope that this tutorial will help you to test your package in production environment before publishing it on npm. With this simple setup you can now test your package the same way as if it was released on the official npm registry.

Originally published at blog.strapi.io on January 24, 2018.