How node package deprecation works

You have probably encountered a warning message saying: "npm WARN deprecated packageX: Use packageY instead, see {link to the repository/web-site}".

This warning is displayed because one of your direct dependency is out of date or one the npm packages in the dependency tree. The same message can be seen also in the central npm registry while browsing for the npm packages such as gulp-rimraf.

The package or it's versions can be deprecated. More about version deprecation at the end of the article.

Here is an example of full deprecation message. It includes name of the alternative package and even a link to example usage.

npm WARN deprecated gulp-rimraf@0.1.1: Use npmjs.org/del instead, see https://github.com/gulpjs/gulp/blob/master/docs/recipes/delete-files-folder.md

Reasons for deprecation

Once you get the warning you should investigate how critical is to change or update the package.

There are several reasons why package or package version might be deprecated:

• other package does the exactly same task (+ it might be more feature-rich)
• plain Node can do the same task and package adds just unnecessary abstraction
• the whole idea of the package was wrong or is wrong in the current light of the industry
• older package version can be deprecated for example when critical security bug is fixed in the newer versions

How does the npm know which packages are out of date and what is the correct alternative?

To display the informative warning message npm uses package.json file. It should contain all the required information about the package, including the deprecation warning. If we look at the package's repository and search for package.json there might not be any information about deprecation, but still we get the deprecation warning. What is going on?

The official package registry itself can have that information. Author of the package can set deprecation data by using command npm deprecate. In order to do this you need to be the owner of the package. This information is extended to the original package.json when fetching the package using npm.

Basic usage:

npm deprecate ping-pong "Ping-pong ain't cool anymore"

Deprecate certain version:

npm deprecate ping-pong@"<1.0.0" "All versions older than v1.0.0 have a bug that prevents paddle to move! Upgrage highly recommended."

Remove deprecation

npm deprecate ping-pong ""

Most of the packages are installed from the main package registry, but sometimes packages are fetched directly from repository. Therefore it's very important to add information to the original package.json and to the readme-file of the repository!

Go on and check your projects warnings. It's always delightful to get rid of those pesty things!