A patch file represents a change to a file and looks like a git diff. Patch files can be kept in source control, and the application of them can be automated in a postinstall script such as npm postinstall. The advantages of this is that you can persist some small changes to your dependencies without all the work of forking the repo, or waiting for the maintainers to release a new version. But use this strategy sparingly, though! If the dependency gets an update, the patch might not work anymore and you might have to update it. Consider it a temporary workaround.

Creating a patch file

So, you’ve encountered a bug in your app. After some investigation you’ve found that the bug is located in the code of the npm package buggybug, which your app is strongly dependent on. By editing the relevant file in the node_modules/buggybug directory, you fix the evil line of code. Great! But since node_modules is included in your .gitignore file, how do you let your teammates enjoy your fix as well? You decide to create a patch file.

Create a patches directory in the root of your repo:

mkdir patches

Copy the fixed file into your patches directory

cp node_modules/buggybug/index.js patches/my-fixed-buggybug.js

Now we want our node_modules to be "clean" again, so why not run a good old

rm -rf node_modules && npm install

After that’s done, let’s create the patch file:

diff -Naur node_modules/buggybug/index.js patches/my-fixed-buggybug.js > patches/buggybug-index.patch

This will create a file called buggybug-index.patch that contains the diff of our change. To apply it to the actual buggybug in node_modules, we use

patch --forward node_modules/buggybug/index.js < patches/buggybug-index.patch

If you inspect your node_modules after running this, you should see that buggybug/index.js is updated with your fixed version.

Now it's safe to delete your fixed copy. We only needed it to generate the patch file.

rm patches/my-fixed-buggybug.js

Applying it on postinstall

In order to automate the application of the patch, we'll add it to the postinstall script in package.json:

// package.json
{
  "scripts": {
    "postinstall": "patch --forward node_modules/buggybug/index.js < patches/buggybug-index.patch",
    ...
  },
  ...
}

Since the postinstall script is run automatically after npm install, all your teammates need to do after a git pull is to run npm install, and your fix is applied. :tada: Test it yourself with rm -rf node_modules && npm install.

And hey! Remember to submit that issue and/or pull request to the dependency's repo!