A short checklist for publishing new major versions of your packages in the npm registry including support for patching older versions.
As your NodeJS packages evolve, there will come the point when you will have to make non-backward compatible changes. According to semantic versioning you should then increase the major version number, e.g. from 1.x.x to 2.x.x.
Table of Contents
Simple package publishing without major changes
So far, most probably all you did to release a new version of your package was to increase the minor (second) or patch (third) version number in your
package.json and simply run
npm publish (including
--access public for scoped packages) to push the new version to the npm registry. Your “versions” tab in the registry will look quite similar to this with one tag called
Now, for advancing to the next major version 2.0.0, there is a bit more to do and think of. Especially, if you want to continue patch support for the 1.x version. You should consider this good style, because your package is actively in use with other projects and not everbody is able to implement the breaking changes immediately.
Checklist for publishing a new major package version
Here are the tasks you should consider when publishing a new major version of a package…
Branching the old version source code
Typically you will be developing your new major version in a separate branch, let’s say
master is holding the code of the currently published package version.
$ git branch master * version-2
To be able to provide further patch support for version 1.x, you need to retain a copy of the code. For that, create a branch
version-1 out of
master and push it to the repository. Ideally, you should do this before merging the new version 2.x code to master.
$ git checkout master $ git checkout -b version-1 $ git push -u origin version-1 $ git branch * master version-1 version-2
Now you have the 1.x sources in a separate branch for patching the old version if needed.
Creating a dist-tag for the old package version
Additionally to the packages version number, npm has so called tags associated with a package. By default, there’s only one tag:
latest. Simply call
npm dist-tag to list all current tags.
$ npm dist-tag latest: 1.0.7
Whenever you do a npm publish without specifying any tag, the new version will be published under the
latest tag. Everytime any user does a npm install or visits the npmjs.com site of your package, he’ll get the last published version for the tag
Now what does this mean? When you need to patch an older version, let’s say v1.0.7 to v1.0.8, after you have already published a new major version v2.0.0, you cannot simply do an
npm publish for the v1.x patch. Doing so would set v1.0.8 as
latest which is not intended!
Luckily, the solution is quite simple. With npm dist-tag you can easily create a new tag, let’s say
stable-v1, for the v1.x branch having the current version 1.0.7. This new tag is then used when you need to publish a patch for the older v1.0.7 version.
$ npm dist-tag add email@example.com stable-v1 $ npm dist-tag latest: 1.0.7 stable-v1: 1.0.7
Having that setup in place, you are ready for potential updates of the old package version without affecting the latest version. See updating an older package version for more details.
Copying and updating the external documentation
As with any new version of a package you should update the documentation in
README.md according to the changes you made. Additionally you will probably have an own website linked via the homepage property in your
I recommend not to create a completely new site for the new major version of the package and change the
homepage property to that. The reason for that is mainly related to search engines…
This is achieved by…
Merging the new version source code
After saving the old versions code in a separate branch, it’s time to merge the new major version to master.
$ git checkout master $ git merge version-2
Publishing the new major version to the npm registry
Make sure that you are in the master branch and the version number in package.json is correctly set to the new major version. Then push the new version to the npm registry.
$ npm publish
Or for scoped packages…
$ npm publish --access public
Heading back to the “versions” tab of your packages site you should see version 2.0.0 released under the latest tag and the recently created tag for the older 1.x version, like so…
Great! You have successfully released the new major version of your package ensuring maintenance for the previous version.
Optional final actions
Although you’re done, I recommend the following optional actions for a for a consistent and qualitative development process.
Creating a tag & release in Git
It’s a good practice to tag published versions in your Git repo and create a release for them. To create the tag, do the following in the master branch.
$ git tag -a v2.0.0 -m "Release 2.0.0" $ git push origin --tags
For creating a release in your Git repo you could either use a command line tool like GitHub CLI or simply switch over to your repos GitHub site. There, it takes only a few clicks:
Releases (right pane) >>
Draft a new release >> Select v2.0.0 tag from branch master and enter a title & description >>
After that you’ll see the latest release version 2.0.0 in the right pane of your repos site.
Deleting the new versions development branch
After merging the
version-2 development branch back to
master, you can get rid of it – both, local and remote.
$ git push -d origin version-2 $ git branch -d version-2
Updating an older package version
Let’s assume you need to patch v1.0.7 to v1.0.8 but v2.0.0 is already released. If you followed the checklist steps mentioned before, your package version & tag situation will look like this.
$ npm dist-tag latest: 2.0.0 stable-v1: 1.0.7
To update the old version v1.0.7, simply do the needed changes in the formerly created branch
version-1. Then increase the version number there to v1.0.8 and publish the new 1.x version directly from this branch using the tag
$ git checkout version-1 # Implement changes & test, set version to 1.0.8, commit to branch $ npm publish --tag stable-v1
This release will not effect the
latest tag, meaning that v2.0.0 is still considered to be the most current version of your package when somebody installs it or visits the packages site. Don’t forget to add
--access public for scoped packages.
$ npm dist-tag latest: 2.0.0 stable-v1: 1.0.8
Happy coding 🙂