Super Easy NPM Package Patching with ‘patch-package’

NPM packages are great. Without them, our lives as developers would be much, much harder. In fact, I’d probably be doing something more fun for a living. Like herding cats. Or juggling chainsaws.

But as great as they are, there will come a time when there’s a bug in one of the NPM packages you use. No problem, right? You create an issue on the package’s GitHub repo. Or, being the professional you are, you create a pull request with the fix.

And then you wait...

And wait…

And w…

Yeah, no. That’s not acceptable.

So you fork the repo and use this as your package source. Or you create your own NPM package from your fork.

But wouldn’t it be great if there were an easier way? A much, much easier way?

Enter patch-package.

Patch-package is the simplest way I have found so far to well.. patch a package.

Yes, it does exactly what it says on the tin.

How to install

Installation is dead simple. Add…

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

…to your package.json file and install patch-package using yarn:

yarn add patch-package postinstall-postinstall

You might notice we’re actually installing two packages, namely patch-package and postinstall. The two work together, as will become clear in a bit.

How to use

To use patch-package, make your changes right in the package code in node_modules and run patch-package. That’s it! It’ll create a patches folder containing the diffs needed to update the package version you installed with the changes you made.

A live example

To show you how it works, I’m going to apply a patch to the react-native-keyboard-aware-view package.

At the time of writing this article, using the <KeyboardAwareView> from the react-native-keyboard-aware-view package results in the following warning:

Which obviously sucks. The fix is rather simple and there are no less than 2 pull requests made on the repo. But the repo seems rather dead. So let’s fix it ourselves.

First, we’ll open up the file node_modules/react-native-keyboard-aware-view\lib\CodeKeyboardAwareView.js. Then we look up all instance of the method call Animated.timing and add the line useNativeDriver: false to the config parameter (there are 3 instances).

Then we reload our app to make sure the warning has gone away. It has, so we successfully patched the package.

Then, we run patch-package:

And voila! Patch-package has created a patch file for us. A snippet from it looks like this:

Which clearly shows the change we made.

Now, because we installed postinstall yarn will run our patches every time we install a new package. We can also force a patch by running patch-package without parameters.

And that’s how easy patch-package makes it to fix a bug in your local code while waiting for your PR (you are still creating a PR, right?) to be merged into the official package.

I have found patch-package incredibly useful. I hope you will, too.

Happy coding!

Super Easy NPM Package Patching with ‘patch-package’