How to patch an NPM dependency

This article is based on Node v16.15.1 and NPM 8.11.0.

You are working on a node/react/angular/... project and, you've discovered that one of your dependencies has a bug. What are you going to do?

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

First, don't panic. There are several options available to fix this:

Package Maintainer

The easiest solution, and only applicable if the project is not time-critical, is to open an issue on the package's Github/Gitlab repository and hope the package maintainer fixes the bug soon.

Unfortunately, this will take a while and, you've got a project deadline at some point.

Fork & Fix it yourself

In my opinion, if you are using open source software try to contribute. Hence, start with fixing the bug in the package yourself. 😀

Fork the broken package’s repository and create a new branch and fix the issue. Push your changes and update your package.json. For example:

"dependencies": {
  "broken-package": "USERNAME/broken-package#BRANCH-WITH-FIX"
}

Now everybody will get a patched version installed when they run npm install or npm update. This has a good side (bugfix), and a not-so-good side (you have to maintain your fork).

Next step is to open a PR/MR with the bugfix on the repository of the package and eventually the PR gets accepted, merged and, a package update published to npm. In this case, simply revert your dependency declaration for the broken-package in package.json and run npm install broken-package.

Use patch-package

Yes, you've read right, there is an NPM package to fix broken packages. 😀

patch-package lets app authors instantly make and keep fixes to npm dependencies.

How it works:

# fix a bug in one of your dependencies
vim node_modules/some-package/brokenFile.js

# run patch-package to create a .patch file
npx patch-package some-package

# commit the patch file to share the fix with your team

git add patches/some-package+3.14.15.patch
git commit -m "fix brokenFile.js in some-package"

Patches created by patch-package are automatically and gracefully applied when you use npm(>=5).

Add postinstall script:

 "scripts": {
   "postinstall": "patch-package"
 }

Install patch-package with flag --save (package is used in production) or --save-dev.

npm i patch-package --save-dev

Make a patch:

npx patch-package package-name

If this is the first time you've used patch-package, it will create a folder called patches in the root directory of your app. Inside will be a file called package-name+0.44.0.patch or similar, which is a diff between normal old package-name and your fixed version. Commit this to share the fix with your team.

Benefits of using patch over fork:

• Sometimes forks need extra build steps
• Get notified when the dependency changed, and you need to check that your fix is still valid.
• Keep your patches co-located with the code that depends on them.
• Patches can be reviewed as part of your normal review process, forks probably can't.

TL;DR

There are three options to fix an NPM dependency:

• Open a bug ticket on the repository of the maintainer
• Fork & Fix
• Create a patch and fix it

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.

If you want to know more about Node, have a look at these Node Tutorials.

References (and Big thanks):

Josh Sutphin, Patch-Package