Prereleases on NPM

by on

So a number of times I have been working on roots and wanted to ship a pre-release version, so that users could install and test out the next version if they wanted, but it wouldn't be the default. I googled this over and over and never found anything that indicated that it was possible, but just the other day I finally figured out a way to do it. So in the spirit of the internets, I'll document it here as a little tutorial and hope that this will help future developers to be able to figure it out more quickly than I did.

So let's say you are working on a new feature and you want to ship it as a prerelease. First, make a branch with your new feature(s), or go to the branch that already has your new feature(s). Make sure you bump the version in your package.json file to whatever the upgrade would be named according to semver, then add a tag like -beta1 to the end. For example, if this was your package.json file before:

{
  "name": "example",
  "version": "1.0.0",
  "description": "example"
}

...and you were going to bump the minor version because you added a new non-breaking feature, and ship a prerelease, this is what you would change it to:

{
  "name": "example",
  "version": "1.1.0-beta1",
  "description": "example"
}

The beta1 tag at the end indicates that its a prerelease, and also allows you to fix up bugs in the process and release again without bumping the main versioning numbers, since those only should be bumped on actual releases. Of course, you can name this however you'd like -- if you prefer alpha1 or rc1 those work as well. Cool, so we're ready to push this to npm now. Let's run the following command:

npm publish . --tag 1.1.0-beta1

Strangely enough, the --tag flag is what npm needs to know that this is not a default release, and although it does not appear that the text after the --tag flag makes any difference, why not just keep it as the version name, just in case. Now, to install your prerelease version, run the following command:

npm install example@1.1.0-beta1

...and you should be set. Note that the version after the at-sign is the version from your package.json file, not the contents of the tag, but in this case it makes no difference since we set the two to be the same.

The fact that you have shipped a prerelease will not show up anywhere on npm (unless you really dig), so if you want people to be able to install it to test, you should document the install command, and of course note that it might not be stable and that they can revert back to the latest stable release any time with a normal npm install. And if you find and fix a bug and want to ship a patch to your prerelease, just bump the beta number and repeat the same process. Finally, when you are ready to ship for real, just remove the -beta flag from your package.json, merge to master, and do a normal npm publish . Cheers!