John Mc Quillan

How to Deploy a Package to npm

While there are various ways to manage your own Javascript library locally or from a git repository, it is more convenient to deploy to npm and consume from there and certainly if you want to share your code publicly, you will at some point want to publish to npm. Here, we’ll guide you through the basic process.

npm Sign Up

In order to publish packages on npm, you need to have an account. If you don’t already have one, go ahead and sign up. A free account will allow you to publish public packages. But, if you want to publish private packages, you will need to sign up for a paid plan.

Getting Started

Create a new folder for your package. You’ll probably want to initialise it as a git repository but we won’t cover that here. To initialise the folder for use with npm, you should run npm init. npm will prompt for various parameters before creating your package.json file. You can change your answers later by editing package.json.

Package Name

One of the parameters you’ll be asked for is your package name. This name needs to be unique in the npm repository, so you won’t be able to use a name that’s already been used by someone else. A bit like .com domain names, you will find that most of the good top level bare names are already gone. However, npm packages can have scoped names of the form @scope/package-name. Since the scope is usually your unique username or organization name, you shouldn’t have too much trouble with a scoped name. Unless you’re planning an open source library that you expect to be very widely used by the community, I would suggest sticking to scoped names for now. Note that private packages will always have scoped names.

Top Level Files


You should create an informative for your package that will explain to potential users how to install the package and call it’s API.


You may want to include a license file that documents the license and ownership of your package. If your package.json has referenced a standard license, you may not need a separate file.

Your Code

Now that you’ve created a package.json file, let’s go ahead and create some code. We’ll come back to package.json later. We’re going to create a CommonJS or cjs module. If you don’t know what that is, don’t worry about it for now. cjs modules are the traditional and default module format for nodejs.

Let’s create a folder called src and a file called index.js in that folder. For now, our library consists of a simple hello-world function.

function helloWorld() {
  return 'Hello World!';

module.exports = helloWorld;

Edit package.json and set the main property to point to this file:-


  "main": "src/index.js",

Testing the Package

We could try publishing the package, install it in another project, import it into an application and try it out. But, that would be a pretty slow dev/test cycle. Instead, it is preferable to test locally first. We’ll cover two different options here.

In the root folder of the library, run the command npm link. This will make the package available globally. Now in a different directory tree, create a folder for a test project. Let’s call it test_hello. Go to that folder and execute the following commands:

npm init -y
npm link @scope/package-name

where scope and package-name are the values you used when creating your library. You can check the name property in the package.json file of the library.

Create a file called test.js with the following content:

const helloWorld = require('@scope/package-name');


If you’ve followed the above steps, you should see Hello World! being output to the command line.

Use npm pack

npm pack will create a tarball, which is effectively the same as the tarball that would be created in the npm repository if we published. As such, using it for testing perhaps gets us a little bit closer to the publish scenario.

From the root folder of your package, execute:

npm pack

This will produce a file with a .tgz extension. The filename will reflect your scoped package name with a version number.

Create and initialize a test folder with the commands:

npm init -y
npm install /<path-to-lib-folder>/<scope-package-name-0.1.0.tgz>

The additional steps are the same as described above for npm link. Once again, running your test script should result in the expected output.

Publish the Package

In order to publish a package to npm, you must be logged in. Execute the command:

npm login

You will be prompted for username and password. You can login to the account you created earlier.

Now execute

npm publish

Depending on how you have set up your multi-factor authentication, you will have to enter appropriate details. You should get a successful response and your package will be available from npm. You can test it in the same way as you tested with npm pack, replacing the initialisation commands with:

npm init -y
npm install @<scope>/<package-name>

Updating the Package

If you update your package, you will want to publish again. When doing so, you must update the version property in package.json. Any attempt to publish with a version that has previously been used will result in an error.

You probably won’t want version numbers to increment too quickly when you are developing new features in your package. While npm link and npm pack help in this regard, they may not cover all aspects of your dev/test cycle. One way you can deal with this is to use alternative version names e.g. alpha versions. To publish an alpha version:

npm version --no-git-tag-version 0.1.1-alpha1
npm publish -tag alpha

Then, to install the latest alpha version in your test project:

npm i @<scope>/<package-name>@alpha

Wrapping Up

This guide should get you started with creating npm packages. We have only covered cjs packages in this article. In a future article, we’ll cover how to publish esm packages and how you might approach universal packages, that can be used by either type of application.


We love to talk about ideas, innovation, technology and just about anything else. Really, we love to talk.

Contact fathom