Be the first user to complete this post

How to publish a package on npm

So, you are ready to publish a package to npm but are not sure how to go about it? This blog post aims to provide one approach to publishing packages onto npm. So, read on, and if something doenst chime, let me know in the comments.

Prerequisites

You have already creaed an account on https://www.npmjs.com/ and can login via the command line using npm adduser - https://docs.npmjs.com/cli/adduser.

Step 1: Local verification

Verify that your package installs locally from another folder.

cd ..
mkdir test-mypackage
cd test-mypackage
npm i ../test-mypackage

You can now use the node command line to require and test your package node

var mypackage = require('mypackage');

To see what gets published to npm, create a tarball in your package directory using

cd mypackage
npm pack

To list the contents of the generated tar file

tar -ztvf mypackage.tgz

By default npm packages the current directory. So be mindful of the branch that is checked out.

Step 2: Managing the publish process

Lets assume you are working on mypackage whose current stable version in the master branch, as specified in package.json is 1.2.0. Your have some new features ready go to into 1.3.0, but you're not sure how stable your changes are. Here's one way of thinking about the release process. - By default, all existing users should continue to get 1.2.0 - 1.2.x upon running npm install. - Certain users should receive the next version, which in this case is 1.3.x, of the project, but they should not have to speficy the exact version all the time. You can achieve this by using dist tags when publishing a package.

Think of dist tags as channels to which users can subscribe.

When you publish your package simply using npm publish command its gets published and assigned to the latest tag. As a consumer of a package, it implies that when I type npm install mypackage, npm looks at the registry and tries to find the published version that is tagged with the latest tag, and installs that version. So if you want beta/test users to install a new version release, all you gotta do is tag associate it with a different tag. e.g. In our case, here's what we can do Checkout a new branch and name it based on your release. E.g.

git checkout -b release/1.3.0

In this branch update the version number in your package.json

npm version 1.3.0-rc.1

This automatically updates the version in your package.json and commits. It also creates a git tag for you.

As per the docs, do not begin your tags with the character v.

You can list all the available git tags using the command

git tag

Now your goal is to publish the package on npm, and assign it a dist-tag. Several projects use the convention of a next tag to denote upcoming releases, so we will follow that same convention.

npm publish --tag next

This will take the current directory (hence the current checked out branch), run build scripts if any, and publish it to npm. It will also tag it with a label called next. Now, your users can install the package using

npm install mypackage@next
OR
npm install [email protected]

This way, in the future, when you have another release candidate for 1.3, lets call it 1.3.0-rc.2, you can run the following commands

npm version 1.3.0-rc.2
npm publish --tag next

And as long as your users are using mypackage@next, they will automatically get the changes in 1.3.0-rc.2 without having to specify the exact number. If they wish to, they can still explicitly choose to install a particular version using npm install [email protected] or npm install [email protected]

BONUS There is also a package semantic-release that you could look at if you need something more automated.

I hope you find this flow useful. If you feel there are ways I could improve this, I will be happy to learn.

References

http://jbavari.github.io/blog/2015/10/16/using-npm-tags/
https://blog.github.com/2013-07-02-release-your-software/
https://medium.com/@alexishevia/the-magic-behind-npm-link-d94dcb3a81af
https://gist.github.com/schmich/d04acc4b02b45e489f329cfdf3280a3f