npm deprecate is a command that lets you mark older versions of your package as obsolete.
Here’s how it works: npm deprecate <package-name>@<version-range> <message>
Let’s say you have a package called my-awesome-lib and you want to deprecate versions 1.x and 2.x because you’ve released 3.0.0 with breaking changes and better features. You’d run:
npm deprecate my-awesome-lib@">=1.0.0 <3.0.0" "This version is deprecated. Please upgrade to v3.0.0 or later for bug fixes and new features."
When someone tries to install your package and a deprecated version falls within the range they’ve specified (either directly or through a dependency), they’ll see your message.
For example, if another package another-lib has my-awesome-lib@^1.5.0 as a dependency, and the user tries to install another-lib, they’ll get a warning like this:
npm WARN deprecated my-awesome-lib@1.5.0: This version is deprecated. Please upgrade to v3.0.0 or later for bug fixes and new features.
This is incredibly useful for guiding users away from outdated, potentially buggy, or insecure versions of your code without actually removing them from the npm registry. Removal is a much more drastic step and can break builds for countless projects. Deprecation is a polite, informative nudge.
You can deprecate specific versions, version ranges, or even the entire package. To deprecate all versions of my-awesome-lib:
npm deprecate my-awesome-lib "*" "This package is no longer maintained. Please migrate to a different solution."
The version range uses standard npm semver syntax, so you can be very precise. For instance, to deprecate only patch versions of 1.2.x:
npm deprecate my-awesome-lib@1.2.* "Patch versions of 1.2 are no longer supported. Please use 1.2.5 or later."
The message is plain text, but it’s your opportunity to explain why it’s deprecated and what users should do instead. This is crucial for effective communication. A good message will include:
- A clear statement of deprecation.
- The reason for deprecation (security, bugs, new features, breaking changes).
- A recommendation for the replacement version or package.
- A link to documentation or a migration guide if applicable.
You can check the deprecation status of a package by looking at its package.json on the npm website, or by running npm view <package-name>. The deprecation information is stored in the registry. When you run npm deprecate, you’re essentially updating a field in the npm registry’s metadata for your package.
The deprecation itself doesn’t change any published versions. They remain available for installation. What changes is the signal that npm sends to users and tooling. This signal is a warning, not an error, so installations won’t fail by default, allowing for a gradual transition.
If you ever need to reverse a deprecation, you can do so by deprecating the same range with an empty message:
npm deprecate my-awesome-lib@">=1.0.0 <3.0.0" ""
This effectively removes the deprecation warning for that specific range. It’s good practice to clean up deprecations once they are no longer relevant, or if you accidentally deprecated something.
While deprecation is a powerful tool, it’s important to use it judiciously. Overuse of deprecation warnings can lead to "warning fatigue," where users start ignoring all warnings, defeating the purpose. Reserve it for versions that truly need to be avoided.
The next step after deprecating old versions is often to consider unpublishing them, but that’s a much more permanent and potentially disruptive action.