npm-dist-tag

List all distribution tags for a package

$ npm dist-tag ls [package_name]

$ npm dist-tag ls

$ npm dist-tag add [package_name]@[version] [tag]

$ npm dist-tag rm [package_name] [tag]

$ npm dist-tag add [package_name]@[version]

$ npm dist-tag add [package_name]@[version] [tag] --otp [one_time_password]

npm dist-tag add <pkg>@<version> [<tag>]
npm dist-tag rm <pkg> <tag>
npm dist-tag ls [<pkg>]
When run in a package directory, <pkg> and @<version> can often be omitted, inferring from package.json.

add @ []
    Adds a new distribution tag, or updates an existing one, to point to a specific version of a package. If <tag> is omitted, it defaults to latest. If run within a package directory, <pkg> and @<version> are inferred from package.json and its current version.

rm
    Removes the specified distribution tag from a package. If run within a package directory, <pkg> is inferred from package.json.

ls []
    Lists all distribution tags and the versions they point to for a given package. If <pkg> is omitted, it lists tags for the package in the current directory.

The npm dist-tag command is a utility for managing distribution tags associated with a package in the npm registry. Distribution tags, often referred to as "dist-tags," are human-readable labels that can be assigned to specific versions of your package. They allow users to install a package by a meaningful name instead of a precise version number, for example, npm install <pkg>@latest or npm install <pkg>@beta. The latest tag is the default one and typically points to the most recent stable release. This command allows you to add new tags, remove existing tags, and list all current tags for a package. It's crucial for maintaining different release channels (e.g., stable, beta, alpha, long-term support) and ensuring users can easily access the desired version of your software.

• Permissions: You must be an owner of the package to modify its dist-tags.
• latest tag: While you can modify the latest tag, it's generally recommended to let npm publish manage it. Publishing a new version with no specific tag will automatically set the latest tag to that new version.
• Security: Be cautious when using tags other than latest for production dependencies, as they might point to unstable versions or be changed unexpectedly by the package maintainer.
• Package Scope: When not specifying a package, the command operates on the package defined in the current directory's package.json.

When you publish a package without specifying a tag option (npm publish --tag <tag>), it will automatically update the latest dist-tag in the registry to point to the newly published version. This is the standard behavior for stable releases.

• Beta/Alpha Releases: Assigning beta or alpha tags to pre-release versions (e.g., npm dist-tag add my-pkg@1.2.0-beta.1 beta). Users can then install my-pkg@beta.
• LTS Versions: Marking long-term support versions (e.g., npm dist-tag add my-pkg@3.0.0 lts-3).
• Canary Builds: Pointing to nightly or very unstable builds for early testing.

The concept of distribution tags has been an integral part of the npm registry and CLI from its relatively early days, designed to facilitate package versioning and release management. While the core functionality of dist-tag has remained consistent, its implementation and integration within the broader npm ecosystem have evolved alongside the npm CLI itself. This command provides a simple yet powerful interface to manage critical release channels, allowing maintainers to easily direct users to stable, beta, or other designated versions without requiring explicit version numbers. It became increasingly important as more complex release strategies, like semantic release and long-term support (LTS) versions, became prevalent in the Node.js and JavaScript communities.

npm-publish(1), npm-install(1), npm-view(1), npm-owner(1)