How to Prerelease an npm Package

Recently, we overhauled our shared ESLint config, and while testing, I needed to release an alpha version. I knew this was possible, but I had no idea how to do it. Thankfully, it turns out to be straightforward, once you know how to do it.

Normally, when we bump the version number of an npm package, we use the npm version command. This automatically increases the version number in both package.json and package-lock.json, as well as making a git commit and git tag with the new version. It follows the Semantic Versioning (SemVer) standard of MAJOR.MINOR.PATCH.

You can control how the version number is incremented by specifying what type of release you’re making. Let’s assume the current version of my npm package is 23.1.6.

• npm version major changes 23.1.6 to 24.0.0
• npm version minor changes 23.1.6 to 23.2.0
• npm version patch changes 23.1.6 to 23.1.7

SemVer also documents how to specify prerelease versions, by using a hyphen. For a traditional prerelease cycle of alpha, beta, then production, you could just use 24.0.0-alpha, 24.0.0-beta, and 24.0.0. However, most of the time you’ll need to release multiple versions of your alpha and beta. You can do that by appending a version number, like 24.0.0-alpha.3.

The npm version command handles creating these prerelease versions in a clever way. By specifying premajor, preminor, or prepatch, it will add a hyphen and a version number. You can also specify the identifier for your prerelease (e.g., “alpha”) by passing the --preid option.

• npm version premajor changes 23.1.6 to 24.0.0-0
• npm version premajor --preid=alpha changes 23.1.6 to 24.0.0-alpha.0
• npm version preminor --preid=alpha changes 23.1.6 to 23.2.0-alpha.0
• npm version prepatch --preid=alpha changes 23.1.6 to 23.1.7-alpha.0

From that point on, you can increase the prerelease version number using the command npm version prerelease.

• npm version prerelease changes 24.0.0-alpha.0 to 24.0.0-alpha.1
• npm version prerelease changes 23.2.0-alpha.0 to 23.2.0-alpha.1
• npm version prerelease changes 23.1.7-alpha.0 to 23.1.7-alpha.1

Then, when you’re ready for the actual release, you use the regular npm version command:

• npm version major changes 24.0.0-alpha.1 to 24.0.0
• npm version minor changes 23.2.0-alpha.1 to 23.2.0
• npm version path changes 23.1.7-alpha.1 to 23.1.7

Now that you know how it works, you can create prerelease versions easily! But there’s one more thing to be aware of.

(Thanks to Jason Raimondi for his article on creating prerelease versions.)

Perhaps you’ve seen some npm packages that tell you to use npm install example-package@next or npm install example-package@latest? It turns out that npm has tags, just like git, which point to particular versions of the package.

When you npm publish a new version of your package, unless you specify otherwise, the new version will get the latest tag, even if it’s a prerelease version!

This is bad, because if someone installs your package without specifying a tag (npm install example-package), then npm install will default to the latest tag. Meaning, in this case, they’d get your prerelease version!

This is not what we want, but the fix is simple. Specify a tag when publishing your prerelease version: npm publish --tag next will publish your new version as normal, but instead of getting the latest tag, it will use the next tag.

Now when users install your package without specifying a tag, they’ll get your latest release version, not your prerelease version. Bonus: By using the next tag, you made testing your prerelease version easier, because your testers can install it using npm install example-package@next and will automatically get the latest version of your prerelease!

Later, when you’re ready for the actual release, use the npm publish command without specifying a tag, and your final release will get the latest tag as normal, and be available for all users.

(Thanks to Mike Bostock for his article on publishing prerelease versions.)

Once you publish the actual release, you’ll want to remove the next tag to avoid confusing users. You can do this using the npm dist-tag command, like so:

npm dist-tag rm example-package next

Running that command will remove the next tag from example-package.

(Thanks to Julian Knight in the comments for suggesting this.)

Prereleasing an npm package is straightforward, if you remember these steps:

• npm version premajor --preid=alpha to create an alpha version of your next major release.
• npm version prerelease to increase the version of your alpha.
• npm publish --tag next to publish your alpha version without affecting all users.
• npm version major to promote your alpha to the next major version.
• npm publish to publish your next major version for all users.
• npm dist-tag rm example-package next to remove the next tag.