How to create a 'canary' release on npm

This post will show how to create a canary release for an npm package.

tldr;

npm version --preid canary preminor
npm publish --tag canary

canary testing

In short, canary testing is a way to publish packages without affecting all users. Users will have to opt-in to use a canary release.

versioning

The version command has a few built in options.

If our package is at 1.1.0 then running npm version minor will update the package.json to 1.2.0. Additionally, it will update package-lock.json and npm-shrinkwrap.json and add a git tag.

To update 1.1.0 to a canary version, run:

npm version --preid canary preminor

This updates the version to 1.2.0-canary.0.

To make updates to this version, run:

npm version --preid canary prerelease

This updates the version to 1.2.0-canary.1.

publishing

To ensure that the canary branch isn't published to @latest, it can be tagged.

To do so, run:

npm publish --tag canary

This ensures that when a user runs:

npm i your-pkg

That it installs the latest, stable, release.

To install the canary version, they must run:

npm i your-pkg@1.2.0-canary.1

summary

npm version --preid canary preminor # go from 1.1.0 to 1.2.0-canary.0
npm version --preid canary prerelease # go from 1.2.0-canary.0 to 1.2.0-canary.1
npm publish --tag canary # publish your-pkg@1.2.0-canary.1