Patch Package

8.0.1 · active · verified Sun Apr 19

patch-package is a utility that enables developers to apply and manage local modifications to their `node_modules` dependencies without needing to fork or wait for upstream merges. It works by creating `.patch` files based on manual changes made directly in `node_modules`, which are then automatically applied during subsequent `npm install` or `yarn install` operations via a `postinstall` script. The current stable version is 8.0.1, with major releases occurring periodically to address Node.js version updates, security fixes, and compatibility with new package manager features. Key differentiators include its simplicity in generating and applying patches, avoiding the overhead of maintaining forks, and providing a quick workaround for urgent bugs in dependencies. It primarily serves as a band-aid solution, especially for projects on the bleeding edge of dependency versions, though newer package managers like Yarn 2+ and pnpm have integrated native patching capabilities that supersede patch-package for those ecosystems. Its release cadence is reactive to critical issues and ecosystem changes.

Common errors

```
Command failed: patch-package Cannot run in wd /app
```
cause This error frequently occurs in Docker environments when `npm` scripts execute in a non-standard working directory or encounter permission issues, potentially related to `.npmrc` settings.

fix Adjust `.npmrc` settings, possibly adding `unsafe-perm = true`, or verify that your Dockerfile copies the project to `/app` (or similar) before running `npm install`, ensuring correct permissions and working directory setup.
```
Error: No patch file found for <package-name>@<version>
```
cause The required patch file for a specific package version is missing from the `patches/` directory or was not copied into the build environment (e.g., Docker image) before `npm install`.

fix Verify that the `patches/` directory and its contents are correctly committed to version control and copied into your build environment. Ensure the patch file name exactly matches the package name and version.
```
The patch file was for version x.y.z but the package is version a.b.c.
```
cause The version of the dependency currently installed in `node_modules` does not match the version that the `.patch` file was originally created for. This often happens after a dependency update.

fix Manually re-apply your changes to the updated dependency in `node_modules`, then run `npx patch-package <package-name>` to generate a new patch file that matches the current version.

Warnings

breaking Version 8.0.0 removed some old legacy filename handling. While not extensively detailed, users relying on specific, non-standard patch file naming conventions from very old versions might encounter issues.
Fix: Re-generate existing patch files using `patch-package` on version 8 to ensure they adhere to current naming conventions.
breaking Version 7.0.0 introduced a breaking change by bumping the minimum required Node.js version from 8 to 14. This was necessary to address a security vulnerability in the `yaml` dependency.
Fix: Upgrade your Node.js environment to version 14 or higher. Projects running on older Node.js versions will fail to install `patch-package@7` and above.
gotcha `patch-package` is not needed for projects using Yarn 2+ or pnpm, as these package managers offer native support for patching dependencies via `yarn patch` and `pnpm patch` respectively.
Fix: For Yarn 2+ or pnpm projects, utilize their built-in patching mechanisms (`yarn patch` / `pnpm patch`) instead of `patch-package`.
gotcha When deploying to Heroku, `patch-package` relies on the `postinstall` script, which is often skipped in production builds. You must explicitly disable production optimizations for Node.js.
Fix: Set the environment variable `NPM_CONFIG_PRODUCTION=false` or `YARN_PRODUCTION=false` in your Heroku application settings to ensure `postinstall` scripts run.
gotcha In Docker or CI environments that cache `node_modules`, changes to patch files might not be reflected if the `patches/` directory is not included in the cache key.
Fix: Ensure your cache key includes a checksum or hash of the `patches/` directory (e.g., `md5sum patches/*`) to invalidate the cache when patches are updated.

Install

npm install patch-package npm
yarn add patch-package yarn
pnpm add patch-package pnpm

Quickstart

Demonstrates the typical workflow for fixing a node module: manual edit, patch creation via CLI, automated application via postinstall script, and committing the patch file.

/*
  patch-package is primarily a CLI tool and typically integrated into package.json scripts.
  This quickstart demonstrates the general workflow.
*/

// 1. Manually identify and fix a bug in one of your node_modules dependencies.
//    Example: open 'node_modules/some-package/brokenFile.js' and apply your fix.
//    (This step involves direct file editing, not code here)

// 2. Generate a patch file for the modified package using npx.
//    Replace 'some-package' with the actual name of your modified dependency.
//    Run this in your terminal from the project root:
// npx patch-package some-package

// 3. Configure your package.json to automatically apply patches during installation.
//    Add this entry to your 'scripts' object:
/*
"scripts": {
  "postinstall": "patch-package"
},
*/
//    If using Yarn v1, you must also install 'postinstall-postinstall' and use:
//    "postinstall": "postinstall-postinstall || patch-package"

// 4. Commit the generated patch file to your version control system (e.g., Git).
//    The file will be located in a 'patches/' directory, named like 'patches/some-package+3.14.15.patch'.
// git add patches/some-package+3.14.15.patch
// git commit -m "Fix brokenFile.js in some-package using patch-package"

// 5. From now on, any 'npm install' or 'yarn install' will automatically apply your patch.

view raw JSON →