Contact Us

How to fork & patch npm modules

Posted on 26/7/11 by Felix Geisendörfer

With now more than 3000 modules, there are huge gaps in the quality of things you find in the npm registry. But more often than not, it's easy to find a module that is really close to what you need, except if it wasn't for that one bug or missing feature.

Now depending on who is maintaining this module, you may get the problem resolved by simply opening a GitHub issue and waiting for a few days. However, open source doesn't really work without community, nor do you always want to be at the mercy of someone else. So a much better approach is to actually roll up your sleeves, and fix the problem yourself.

Here is the proper way to do this while using npm to manage your forked version of the module:

  1. Fork the project on GitHub
  2. Clone the fork to your machine
  3. Fix the bug or add the feature you want
  4. Push your commits up to your fork on GitHub
  5. Open your fork on GitHub, and click on the latest commit you made
  6. On the page of that commit, click on the "Downloads" button
  7. Right click on the "Download .tar.gz" button inside the popup, and copy the link ("Copy Link Address" in Chrome)
  8. Open up your package.json file, and replace the version number of the module with the url you just copied
  9. Send a pull request upstream (Optional, but this way you will avoid having to maintain that patch of yours against newer versions of the module you forked)

Example: My new airbrake module uses a forked version of xmlbuilder. I submited my fix as a pull request, but it has not been merged yet. In order to pull in my changes via npm anyway, I simply pointed my package.json to the download url of my fork on GitHub like so:

"dependencies": {
    "request": "1.9.8",
    "xmlbuilder": "",
    "stack-trace": "0.0.5",
    "traverse": "0.4.4",
    "hashish": "0.0.4"

Alright, let me know if this is helping your node.js adventures, or if you have an alternative workflow you are using. Otherwise, happy hacking!


PS: You should upgrade to the latest npm version first, some older versions had problems with handling url dependencies properly.


You can skip to the end and add a comment.

Greg  said on Jul 26, 2011:

Awesome tip, thanks Felix!

This post is too old. We do not allow comments here anymore in order to fight spam. If you have real feedback or questions for the post, please contact us.