patch-package

library8.0.1jsnpmunverified

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.

devops

npm install patch-package

github ↗package ↗

INSTALL

IMPORT

SIG · PATCH-PACKAGE

patch-package

devopsjavascriptv8.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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.

patch-package --version

Debug

Known issues

breakingVersion 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.

affects: >=8.0.0

breakingVersion 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.

affects: >=7.0.0

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`.

affects: All versions

gotchaWhen 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.

affects: All versions

gotchaIn 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.

affects: All versions

Errors

Common errors & fixes

Command failed: patch-package Cannot run in wd /app

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>

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.

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.

Upgrade

Version history

8.0.1latest on npm

Audit

Dependencies

postinstall-postinstalloptionalRequired for Yarn v1 to correctly run the postinstall script due to Yarn's specific script handling quirks. Not needed for npm or newer Yarn versions.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ds300/patch-package ↗

packagehttps://www.npmjs.com/package/patch-package ↗