DEV Community

loading...

How to patch an NPM dependency

Mario
Software Engineer from Vienna, Austria. Building things, mainly in JavaScript.
Originally published at mariokandut.com on ・5 min read

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?

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.

💰: $100 (credits) for you to start your cloud journey with DigitalOcean!

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"
}
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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

Add postinstall script:

 "scripts": {
   "postinstall": "patch-package"
 }
Enter fullscreen mode Exit fullscreen mode

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

npm i patch-package --save-dev
Enter fullscreen mode Exit fullscreen mode

Make a patch:

npx patch-package package-name
Enter fullscreen mode Exit fullscreen mode

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

Discussion (0)