Modifying Tags on NPM

At its core, publishing a package to the NPM registry boils down to a single command:

npm publish

There is, however, more nuance once we dig below the surface. In this article, I'll briefly cover the concept of tags from the perspective of a publisher.

NPM supports tagging versions of a package¹. Tags are essentially aliases for a particular version. The latest tag is applied by default any time a new version of a package is published.

If you want users to be able to opt in to download a prerelease version of your package via the NPM registry, you'll likely want to avoid publishing that prerelease version of your package with the latest tag. Assume we were working on a package that was on version 1.0.0. We could publish a minor prerelease version by first bumping the version in the local package.json to 1.1.0-beta.0², then using the —-tag flag to declare a custom tag as shown:

npm publish --tag beta

This would push version 1.1.0-beta.0 of the package to the NPM registry and apply the custom beta tag.

Mistakes do happen and it's well within the realm of possibility that we misspell the beta tag or forget to declare it in the first place. Let's explore the latter situation: we accidentally published version 1.1.0-beta.0 of our package without specifying the tag to be used — causing it to default to the latest tag. Thankfully, it's possible to modify the tag of an already published package version by using npm dist-tag. To apply the beta tag retroactively, we'd use the following command:

npm dist-tag add [email protected] beta

Doing so applies the beta tag to version 1.1.0-beta.0 of our package. It also has another side effect: the latest tag will be moved to the previously published version of our package: 1.0.0. This happens because, in the NPM registry, a single version of a package cannot have multiple tags at the same time.

Footnotes

1. The tagging system has 2 rules:

   1. There is an "optional" (see the next rule below) 1-to-1 bidirectional mapping between a version and a tag, i.e., a version can have at most one tag and a tag can be applied to at most one version.

   2. The latest tag must exist.

   ↩︎

2. While modifying the version number manually in the package.json is totally fine, the npm CLI also provides a way to do just this. Bumping the version from 1.0.0 to 1.1.0-beta.0 can be done by running the following command:

   npm version preminor --preid=beta

   The following command can then be used to bump the prerelease version form 1.1.0-beta.0 to 1.1.0-beta.1:

   npm version prerelease

   When ready to release a stable version, going from 1.1.0-beta.1 to 1.1.0 can be done with the more familiar:

   npm version minor

   ↩︎

Sources

• npm-dist-tag docs