Publish your first npm package

If you have been working with JavaScript and it’s ecosystem, for sure you have thought: “I would like to contribute to this great community”. But how to do it? That’s what we are going to explain in this article.

Prerequisites

In order to start working on your package, you need to install NodeJS and npm on your machine. There are couple of ways to do it, but the simplest one is to go to https://nodejs.org/en/ site and click on download button (for official packages and long-term projects I advice using LTS version).

After you have installed NodeJS you should verify that it is installed properly. Open up a terminal and type node -v. It should return a version that you have installed. Next, type npm -v. You should also see installed version of it. With that out of your way, you are ready to go!

Develop the thing

First thing that you need to come up with is what you are going to build. For our example we are going to build simple module that capitalizes provided string (just a dummy example).

Initialize the project with npm init in terminal. Terminal will prompt you with couple of questions and the most important question that you need to answer is the name of the package. We will call it super-uppercaser. Open folder in your favorite text editor and create file called index.js. Make sure that main option in package.json file is pointing to this newly created index file as that file will be imported when user requires your package. Content of your package.json file should be something like this:

{
"name": "super-uppercaser",
"version": "1.0.0",
"description": "Just a dummy npm package",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT"
}

Other thing that is important is version of the package, in our case it’s 1.0.0. npm suggests that all packages have that as their starting version, but we we will come back to that later.

Open index.js and add following code to it:

module.exports = function (string) {
return string.toUpperCase();
}

As you can see it doesn’t do much, but it will do for our example. When you are happy with how your code looks it is time to publish it. Or it isn’t?

Use your package

It would be really nice if you could require your package from another project before you publish it on npm. As it appears, there is a npm link utility that we can use for exactly this purpose.

What npm link does is that it creates a symlink (shortcut) of a folder where you are positioned when you invoke it, to your global npm packages folder. It works almost the same as if you have installed that package globally with npm install -g {package_name}.

In your terminal position in the folder of your package and type npm link. Terminal should return back to you the location of created symlink. Next, create another project in a separate folder and type npm init -y (this will initialize package.json with default values). Type npm link super-uppercaser. This will create a shortcut to our little npm package from global node_modules folder to our new project’s local node_modules. This means that we can require that package in our new project.

Create index.js file, open it in your favorite editor and require your package:

var superUppercased = require('super-uppercaser');
console.log(superUppercaser('this works'));

Test if it works by executing this command in terminal:

node index.js

You should see terminal outputting upper-cased function parameter.

With npm link we can continue working on our package and have a real world application that uses it. Once we are satisfied with our package functionalities, we can publish it to npm so everybody can benefit from.

Publish package

Let’s publish our little package. First, we should create an account on npm. Head over to https://www.npmjs.com/ and create your account, it is a straightforward process.

Before we publish our package, we should create a readme file for our project. Create README.md in your project and describe your package with as much care and detail as you can, because this is the description that other developers will read before they decide to install your package.

Once you have completed your registration and have created readme file, open up your terminal and type npm login. It will ask for your username and password and with that you are ready to publish your package!

Position yourself in your package folder in terminal, and type npm publish. npm will start uploading your package to it’s registry. If package name is taken, npm will say that you don’t have a permission to publish that package. If that is the case, choose different name, update package.json file with that new name and execute publish command again. With that out of our way, go to your profile page on npm, and you should see your first package published! Congratulations!

Maintaining your package

Remember how I said that initial version of your package should be 1.0.0? That isn’t by accident. npm packages should do their versioning based on semver.

What this versioning convention says is that your package version should be constructed out of three parts: patch version, minor version, and major version. Patch version is changed whenever you fix some bug in backward compatible way, minor version is changed when you add some feature in backward compatible way, and major version is changed when you make some breaking change in your package.

For example, let’s say that we want out package to also replace all spaces with empty characters and then do it’s uppercase thing (because this is what everyone is asking us to do). This will cause breaking change, as return value isn’t the same as in our previous package version. Let’s update our code:

module.exports = function (string) {
return string.replace(/\s*/g, '').toUpperCase();
}

When we are satisfied with it, update your package.json file’s version to 2.0.0 and in your terminal run npm publish. This will publish new package version to npm.


There is much more than this for creating high quality package, of course. This was just a simple introduction how to publish your package to npm and how to maintain it. High quality package should have: