How to use patch-package to fix npm dependencies

What patch-package does and when to use it

You fix a bug in a file inside node_modules, then run patch-package on that package. It creates a .patch file that records the difference between the original package and your fixed version. You commit that file to your project, and it is applied automatically when npm or yarn installs packages.

The README calls patch-package a band-aid. It is meant for a quick fix while you wait for the upstream maintainer to publish a release, or for a small change that does not justify forking the whole dependency.

• Best fit: a Node.js app that needs a fix before the upstream project publishes one.
• Requires npm 5 or later, or yarn v1.
• Not needed on yarn v2+ or pnpm, which have their own patching commands (yarn patch and pnpm patch).

Install patch-package with npm or yarn v1

First add a postinstall script to the scripts section of your package.json. This tells npm or yarn to run patch-package after each install, so patches are reapplied automatically.

Then install the package. With npm, use npm i patch-package. You can add --save-dev if you do not run npm in production, for example in a web frontend. With yarn v1, the README uses yarn add patch-package postinstall-postinstall. The postinstall-postinstall package is needed for yarn; the README links to a section explaining why.

Make a patch and share it with your team

Change the files of a package inside your node_modules folder. Then run patch-package with the package name. You can use npx, which comes with npm 5.2 or later, or yarn patch-package with yarn.

The first time you run it, patch-package creates a folder called patches in the root of your app. Inside is a .patch file named after the package and its version. Commit that file so your team gets the same fix. To update a patch later, make more changes, run patch-package again, and commit the updated file.

• Use --create-issue for packages hosted on GitHub. It opens a browser with a draft issue based on your diff.
• Use --use-yarn to force yarn when you have both lockfiles. By default npm is used in that case.
• Use --include and --exclude with a regexp to choose which paths are part of the patch. --exclude defaults to package.json.

Apply patches and handle failures

Run patch-package with no arguments to apply all patches in your project. This happens automatically if you set up the postinstall script. Locally, patch-package exits with code 0 even when a patch fails, so that yarn.lock and package.json do not fall out of sync with node_modules. On CI, --error-on-fail is switched on by default.

If you need to apply a patch by hand, the README shows git apply --ignore-whitespace with the patch file path, or the patch command on unix-style systems with -p1.

• --error-on-fail makes patch-package exit with code 1 after a failure.
• --reverse un-applies all patches. It fails if the patched files have changed since they were patched; in that case you will probably need to reinstall node_modules.
• --patch-dir sets the folder where patch files are stored.

Patch nested and scoped packages

If a package is nested inside another, for example node_modules/package/node_modules/another-package, put a slash between the package names. Scoped packages work too.

On yarn workspaces, patch-package needs to be set up in the child package for un-hoisted packages. Run patch-package from inside the child package directory when you generate its patch files.

• Nested: use package/another-package as the name.
• Scoped: use the full scope and name, such as @my/package/@my/other-package.

Handle dev-only dependencies and deployments

If you deploy your package to production, patches to devDependencies may not be present when patch-package runs. If the package is listed directly in devDependencies, patch-package ignores its patch file. If it is a transitive dependency, patch-package cannot tell that it is safe to ignore and throws an error. To avoid this, rename the patch file to add .dev before .patch. These files are safely ignored when NODE_ENV=production.

Heroku needs NPM_CONFIG_PRODUCTION=false or YARN_PRODUCTION=false for patch-package to work. For Docker, copy the patch files before running npm or yarn install. If you cache node_modules in CI, include the patches folder in your cache key so updated patches are picked up.