Releasing JavaScript

Publishing to npm

You've updated your changelog and committed all the changes and you're ready to publish a new version to npm.

Step 1: Increment the package version

The fist thing you need to do is increase the package version based on the rules of semantic versioning, taking into account the changes that you've made since the latest published version. While you could do it by hand, there's also a dedicated command.

npm version < major | minor | patch >

For example, if the current version is 1.5.2, a patch bump would produce 1.5.3:

npm view . version
# 1.5.2

npm version patch
# 1.5.3

The command does a couple of useful things:

Step 2: Publish to npm

npm publish will push the new release to the npm registry.

Step 3: Push the changes to Git

git push origin head --follow-tags

Will push the commit that bumps the library version, along with the newly-created tag for the release.

Publishing pre-releases

In semver, pre-release versions are denoted by a hyphen (-), followed by an identifier, e.g. 1.0.0-beta.12.

To generate a pre-release version automatically, use:

npm version < premajor | preminor | prepatch | prerelease >

...while optionally passing an identifier with the --preid option. Let's say we're working on backwards-incompatible changes and the stable version is 1.5.0. The command below would produce the 2.0.0-alpha.0 version:

npm view . version
# => 1.5.0

npm version premajor --preid=alpha
# => 2.0.0-alpha.0

While on a pre-release version, we can continue to use the npm version prerelease command to continously increase the pre-release version:

npm view . version
# => 2.0.0-alpha.0

npm version prerelease
# => 2.0.0-alpha.1

npm version prerelease
# => 2.0.0-alpha.2

Then publish this version with a distribution tag (dist-tag):

npm publish --tag next

The purpose of dist-tags is to associate package versions with separate development streams. Most projects use just the latest tag, which is the default when using npm install <package> and npm publish <package>.

That's why it's very important to always publish pre-releases with a dist-tag, otherwise they end up on the latest stream, and people installing your package will unexpectedly get an experimental version rather than the latest stable version. See this article by Mike Bostock for more details.