🔴 deprecate an npm package

I recently restructured my eslint configuration, which left my original configuration completely unused. So in order to avoid confusion, I decided to deprecate the old package. Here's how I did it.

👨🏼‍💻 source code

First I added a deprecation message to the readme. I put the message towards the top so visitors can easily see it. As a courtesy, I also linked to the new package so users know what to use instead.

Then I published the readme changes to npm as a new patch version. The two commands below came in handy to bump the version and publish the package, but your deployment setup may vary.

npm version patch
npm publish

More documentation is available on the npm website for the version and publish commands.

📁 github repository

Next I had to archive the repository so that visitors would know it's read only and no longer being supported. The Archive button is under in Settings tab, all the way at the bottom in the Danger Zone.

While this button is in the Danger Zone, you can Unarchive your repository at any time. So don't sweat it too much!

📦 npm package

Finally, I had to let npm know that the package is deprecated. I used the deprecate command to do that. The last parameter is a deprecation message that will show up when a user tries to install a deprecated package

npm deprecate eslint-config-bradgarropy "This package is deprecated."

Once deprecated, npm will show a banner to indicate to users that they should no longer use this package. The banner includes the deprecation message you entered in the npm deprecate command.

⛔ deprecate vs unpublish

But some might say, "That seems like a lot of work. Can't I just delete it?"

While npm does support deleting a package (they call it unpublishing), it is generally not recommended. Other developers may rely on the package you published, and removing it from the registry would disrupt the work those dependent on your package.

In fact, npm has a set of policies on when a package can be unpublished. So if you're looking for guidance on when to unpublish versus when to deprecate, read the documentation on that.

Have you ever deprecated an npm package? If so, let me know your process on Twitter!