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.
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
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
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.x upon running
– 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.
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
You can list all the available git tags using the command
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
Now, your users can install the package using
npm install [email protected] 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
[email protected], they will automatically get the changes in
1.3.0-rc.2 without having to specify the exact number.
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.