How to patch an NPM dependency

How to patch an NPM dependency

Fix a bug in a dependency without waiting for the maintainer

ByMario Kandut

honey pot logo

Europe’s developer-focused job platform

Let companies apply to you

Developer-focused, salary and tech stack upfront.

Just one profile, no job applications!

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.


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

More node articles:

Getting started with Webpack

How to list/debug npm packages?

How to specify a Node.js version

How to create a web server in Node.js

How to dynamically load ESM in CJS

How to convert a CJS module to an ESM

How to create a CJS module

How to stream to an HTTP response

How to handle binary data in Node.js?

How to use streams to ETL data?

How to connect streams with pipeline?

How to handle stream errors?

How to connect streams with pipe?

What Is a Node.js Stream?

Handling Errors in Node (asynchronous)

Handling Errors in Node.js (synchronous)

Introduction to errors in Node.js

Callback to promise-based functions

ETL: Load Data to Destination with Node.js

ETL: Transform Data with Node.js

ETL: Extract Data with Node.js

Event Emitters in Node.js

How to set up SSL locally with Node.js?

How to use async/await in Node.js

What is an API proxy?

How to make an API request in Node.js?

How does the Event Loop work in Node.js

How to wait for multiple Promises?

How to organize Node.js code

Understanding Promises in Node.js

How does the Node.js module system work?

Set up and test a .env file in Node

How to Use Environment Variables in Node

How to clean up node modules?

Restart a Node.js app automatically

How to update a Node dependency - NPM?

What are NPM scripts?

How to uninstall npm packages?

How to install npm packages?

How to create a package.json file?

What Is the Node.js ETL Pipeline?

What is data brokering in Node.js?

How to read and write JSON Files with Node.js?

What is package-lock.json?

How to install Node.js locally with nvm?

How to update Node.js?

How to check unused npm packages?

What is the Node.js fs module?

What is Semantic versioning?

The Basics of Package.json explained

How to patch an NPM dependency

What is NPM audit?

Beginner`s guide to NPM

Getting started with Node.js

Scroll to top ↑