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.
Creating the prerelease version
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 majorchanges23.1.6to24.0.0npm version minorchanges23.1.6to23.2.0npm version patchchanges23.1.6to23.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 premajorchanges23.1.6to24.0.0-0npm version premajor --preid=alphachanges23.1.6to24.0.0-alpha.0npm version preminor --preid=alphachanges23.1.6to23.2.0-alpha.0npm version prepatch --preid=alphachanges23.1.6to23.1.7-alpha.0
From that point on, you can increase the prerelease version number using the command npm version prerelease.
npm version prereleasechanges24.0.0-alpha.0to24.0.0-alpha.1npm version prereleasechanges23.2.0-alpha.0to23.2.0-alpha.1npm version prereleasechanges23.1.7-alpha.0to23.1.7-alpha.1
Then, when you’re ready for the actual release, you use the regular npm version command:
npm version majorchanges24.0.0-alpha.1to24.0.0npm version minorchanges23.2.0-alpha.1to23.2.0npm version pathchanges23.1.7-alpha.1to23.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.)
Publishing the prerelease version
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.)
Removing the prerelease version
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.)
Conclusion
Prereleasing an npm package is straightforward, if you remember these steps:
npm version premajor --preid=alphato create an alpha version of your next major release.npm version prereleaseto increase the version of your alpha.npm publish --tag nextto publish your alpha version without affecting all users.npm version majorto promote your alpha to the next major version.npm publishto publish your next major version for all users.npm dist-tag rm example-package nextto remove the next tag.
We’re Cloud Four
We solve complex responsive web design and development challenges for ecommerce, healthcare, fashion, B2B, SaaS, and nonprofit organizations.