← Back to 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:
- it increases the version of your package in
package.json
; - if you have Git set up for the project, it creates a new commit for the version change in
package.json
, and a new tag namedvX.Y.Z
.
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.