By Aaron Rackley in Coding — Jul 27, 2023

Patching an npm package

Its scenario time...

You have been debugging an issues in your code base for a few hours and have eventually narrowed down the issue to a third party npm package.

Given this scenario or many such similar, there is a few things you would normally do at this point in time.

Firstly you might head over to the npm packages git repo and raise a bug/issue and wait for them to fix and release a new version. The trouble with this approach is that it relies on the contributor(s) of that package to do the work and as such there is no timeframe usually on how long this can take to resolve.

Secondly. You are a developer, you could fork the repo and make the change yourself and do a PR back into the origin. This is a great approach and my favourite to do because you are also giving back to a package you have been using, which in most cases is always free. There is just one issue with this as well. It once again relies on the contributor(s) of that packages to confirm the PR, merge it into the codebase an make a release, and as above there can be no timeframe to this happening.

"But Aaron, this is a critical bug and I need to get the change made to my codebase yesterday because there is a release due in like 2 hours."

I hear you, that is why your here. Let me help you through this.

So what can we do in the meantime?

The answer is to create a patch for that npm package in your local project repository using a tool such as npm 'patch-package'. This tool allows you to make code changes to a npm package that are applied on top of the package once it has been installed.

So lets walk through how we do that.

🐛 Step 1 : Squash that bug!

Head into the npm package in your node_modules and fix the bug you found. or even for the purposes of this tutorial, just add a simple console.log() somewhere. Just do not tell anyone, we know how much some devs hate seeing that phrase in codebases. For me I will be adding a simple log to 'react-dom'

📦 Step 2 : Install and setup patch-packge

Next we need to grab the patch-package from the npm software registry, we can do this in multiple ways depending on your setup choice.

Via NPM:

npm install patch-package

You can use --save-dev at the end of the above command if you don't need to run npm in production.

Via Yarn:

yarn add patch-package postinstall-postinstall

As above can use --dev at the end of the above command if you don't need to run yarn in production.

⁉️

What is postinstall-postinstall
Yarn only runs the postinstall hook after yarn and yarn add, but not after yarn remove. The postinstall-postinstall package is used to make sure your postinstall hook gets executed even after a yarn remove. This means you can be sure that your patches will only be run after Yarn has finished setting up the packages folder.

Once you have the package we now need to add a new command to your package.json scripts object for running patch-package.

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

🏃 Step 3 : Run your patch

Now that you have made your bug fix inside a npm package of choice and installed patch-package, the next step is to run patch-package. It will find your change and make a patch file that contains commands on the code you changed, added, removed etc.

Via NPM:

npx patch-package package-name

The package-name will be the name of the npm package in which you made the bug fix for.

Via Yarn:

yarn patch-package package-name

As above, package-name will be the name of the npm package in which you made the bug fix for.

Once you run this you will see something similar to this in the terminal window.

patch-package 7.0.2
• Creating temporary folder
• Installing react-dom@18.2.0 with npm
• Diffing your files with clean files
✔ Created file patches/react-dom+18.2.0.patch

💡 react-dom is on GitHub! To draft an issue based on your patch run

    npx patch-package react-dom --create-issue

You will also have noticed a new folder has been added to your projects root called 'patches', this is where this patch and all future patches will live.

You will also notice that because react-dom is on Github. The package allows you create an issue on the repo referencing your code changes.

📦 Step 4 : Re-instal your packages.

And that is it... Now when ever you run your package installer of choice. Once all the packages are installed a postinstall step will be done to instal all your patches.

This is just the tip of the iceberg for what this package can do so make sure to head over to the package site to learn more.

Have you used this package before? Let me know what you think in the comments below or reach to me on twitter @aaron_rackley