patch-package

A utility to patch npm dependencies quickly

Recently found this super useful utility which I think can be useful for a lot of people. If you've spent considerable time in the web ecosystem, you may have run into this situation: You want to change a few lines of code in a dependency. Likely it's a bug in the dependency or a case that the original authors hadn't considered etc or just a change that's specific for your team/organization.

Now at this point, the regular method is to either maintain a fork of that dependency with your changes that you will need to keep in sync with upstream or hope your changes get accepted into the upstream directly. Either way it's a long cumbersome process for a change that could be as small as line or function.

Enter patch-package!

It saves any patches you make to any package in your node_modules folder in a special folder locally. These patch files can be stored in git and shared with your colleagues. The patch-package utility runs in postinstall step to apply all the packages to the corresponding dependencies

Here's a step by step guide on what a workflow with patch-package could look like. Suppose we want to make a change to is-odd package.

• Step 1: Let's assume you've initialized a node project with the entry point main.ts that looks like this:

  // main.ts
  
  import isOdd from "is-odd";
  
  function main() {
      console.log(isOdd(10));
  }
  
  main();
  

• Step 2: Now open the file index.js inside the is-odd package. You can find it inside your node_modules: node_modules/is-odd/index.js. Add your change to the dependency, like here I've added a console log

  // node_modules/is-odd/index.js
  
  module.exports = function isOdd(value) {
  
    // Add this console log in is-odd package
    console.log("comment from inside node module is-odd!")
  
    const n = Math.abs(value);
    if (!isNumber(n)) {
      throw new TypeError('expected a number');
    }
    if (!Number.isInteger(n)) {
      throw new Error('expected an integer');
    }
    if (!Number.isSafeInteger(n)) {
      throw a Error('value exceeds maximum safe integer');
    }
    return (n % 2) === 1;
  };
  

  Tip: Save the changes in dependency without formatting changes in VSCode using "Save without Formatting" option in the command palette :

  

• Step 3: Add "patch-package" in the postinstall script in package.json

  
• Step 4: Run patch-package from root of your repo. I was using bun so this was the command:

  bunx patch-package is-odd

  This will create a patches folder in root of your repo

  

This patches folder can now be added to git and distributed in your team along with the rest of the codebase. The postinstall script will ensure the patches are applied on installing dependencies.

Additional Tips

• --reverse

  Un-applies all patches

• --create-issue

  For packages whose source is hosted on GitHub this option opens a web browser with a draft issue based on your diff.

• Patching the package.json of the dependency

  You can patch the library's package.json with

  patch-package --exclude 'nothing' package-to-be-patched

  source