Managing Package versions with Yarn tag CLI commands

In this tutorial, we will show you how to add, remove or list tags on a package.

What are tags?

The distribution tags (or dist-tags) are a way for you to mark published versions of your package with a label. Users of your package will be able to use this label instead of a version number.

For instance, in the case where you had a stable release channel and a canary release channel, you can use tags as a way of allowing the user to type:

yarn add your-package-name@stable

yarn add your-package-name@canary

The different tags have different meanings:

• latest: This is the current version of the package
• stable: This is the latest stable release of the package; it is normally the same as latest unless you have Long-term Support (LTS)
• beta: This is a release before becoming latest and/or stable, it is used to share upcoming changes before they are finished.
• canary: This is a " nightly" or pre-beta release, if the project is frequently updated and depended on by many people you can use this to share even earlier code.
• dev: This is used when you want to be able to test out a single revision through the registry while you're still working on things.

Some projects make up their own tags as they deem fit or according to one of the more standard ones. An example is the next tag which is the same with beta.

Even though these are widely considered as standard tags, only the latest has a real meaning, it is used to determine the version to install when you don't specify a version.

Caveats

You will not be able to use tags that match potential version numbers since they share a namespace:

yarn add your-package-name@<version>

yarn add your-package-name@<tag>

Additionally, you cannot use a tag that can be used as a valid semver, it will be rejected. For instance, you can't have a tag that is named v2.3 because un semver it means >=2.3.0<2.4.0.

Generally, you need to avoid tags that look like versions, they will typically confuse people anyways.

Commands

yarn tag add <package>@<version> <tag>

This will add a named <tag> for a specific <version> of a <package>

yarn tag remove <package> <tag>

This command will remove a <tag> from a <package> that is no longer in use.

It is advisable to only delete a tag after you have moved it to another version in the package.

yarn tag list [<package>]

This will list all the tags that are available for a <package>. If you do not specify <package> it will default to the package that you are currently in its directory.

Previous: Running Scripts and updating Yarn with CLI commands.
Next: Managing Teams and Running tests with Yarn CLI.