How to rollback an npm package

Mask your broken version and better understand how npm dist-tags works

TL;DR

npm dist-tag add <package-name>@<last-working-version> latest

Context

Here at Outbrain, we work with CI/CD to publish our npm packages, and a few days ago, I updated a small package that the deployment process is using, validated the code, and released the package through our pipeline. The CI ran tests and published the new version. 🎉

But an hour passed, and developers started complaining about pipelines beginning to fail, and I quickly found out that my update was the reason! So quickly, I found the problem and fixed it. But as I ran the pipeline, I got the SAME error that everyone got, and I couldn’t release my fix! 😱

After some more digging, I found out that the CI/CD process always uses the latest version of the package that I updated, and because I broke the latest version of the package, I couldn’t release my fix to update the package. So, what could I do? 🤔

“Latest”

When we want to install a new package to our repo, we can specify a specific version or let npm decide. By default, npm installs the “latest” version, but “latest” doesn’t always mean the newest version.

# install version 1.0.0
npm install npm-rollback@1.0.0
# install the “latest” version
npm install npm-rollback

When we run npm install without specifying a tag, NPM will automatically resolve to the latest tag.

# both are equal
npm install npm-rollback
npm install npm-rollback@latest

Custom Tags

When we publish a new version of our package, npm automatically assigns this new version with the “latest” tag, but we can specify a specific tag instead of “latest.”

npm publish --tag best

This command will publish our newest version under the “best” tag, but what happens to the “latest” tag? Well, we can check by using the dist-tag command. The dist-tag command allows us to list, set, and remove tags.

If we run this command, we’ll see all the tags of our package.

npm dist-tag ls npm-rollback
# output:
# best: 1.0.1
# latest: 1.0.0

As you can see, the newly published version is now under the “best” tag, but the “latest” tag still points to the old version!

If we want to remove the “best” tag, run the following command:

npm dist-tag rm npm-rollback best

To add a new tag, we can run the following:

npm dist-tag add npm-rollback@1.0.1 oreo

Solution

So to mask our flawed version, we can override the latest tag with the working version. In the case of our package, all we need to run is

npm dist-tag add npm-rollback@1.0.0 latest

And that is it! The next time someone will run npm install npm-rollback NPM will install the version 1.0.0 instead of the newest version 1.0.1