Dist-Tags and Prereleases

Dist-Tags, Prereleases and Deprecation

A dist-tag is a mutable pointer from a name to a version. npm 2,036 install express really means "install whatever express@latest points at today". npm's own pointers show how to run a long-lived project:

Every dist-tag on the npm CLI packageShell
npm dist-tag ls npm
Output
latest: 12.0.2
latest-7: 7.24.2
latest-11: 11.19.1
next-12: 12.0.2

latest-N lets someone on npm 7 run npm i -g npm@latest-7 and get the newest release of their major. pnpm 69,400 publishes the same shape (latest-9 through latest-12). Copy the pattern once you support more than one major line.

Prereleases pair with tags. Publishing 1.4.1-rc.0 under --tag rc leaves npm i pkg unaffected while testers run npm i pkg@rc; when the release is ready, npm dist-tag add pkg@1.4.1 latest promotes it without a second upload — and an rc tagged latest by accident still cannot reach a project that asked for ^1.4.0 (Semantic Versioning).

When a version must go, deprecate rather than unpublish:

Marking a range obsolete, then clearing the noticeShell
npm deprecate pkg@"<1.4.0" "Prototype pollution in parse(); upgrade to 1.4.0"
npm deprecate pkg@"1.4.2" ""

The message prints on every install of a matching version and appears on the package page, while existing installs keep working. An empty string undoes it. Moving a dist-tag and deprecating a range are reversible and touch only new installs; unpublishing is neither, which is why it is the last resort.