{"id":14802,"library":"patch-package","title":"Patch Package","description":"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.","status":"active","version":"8.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/ds300/patch-package","tags":["javascript"],"install":[{"cmd":"npm install patch-package","lang":"bash","label":"npm"},{"cmd":"yarn add patch-package","lang":"bash","label":"yarn"},{"cmd":"pnpm add patch-package","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required 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.","package":"postinstall-postinstall","optional":true}],"imports":[],"quickstart":{"code":"/*\n  patch-package is primarily a CLI tool and typically integrated into package.json scripts.\n  This quickstart demonstrates the general workflow.\n*/\n\n// 1. Manually identify and fix a bug in one of your node_modules dependencies.\n//    Example: open 'node_modules/some-package/brokenFile.js' and apply your fix.\n//    (This step involves direct file editing, not code here)\n\n// 2. Generate a patch file for the modified package using npx.\n//    Replace 'some-package' with the actual name of your modified dependency.\n//    Run this in your terminal from the project root:\n// npx patch-package some-package\n\n// 3. Configure your package.json to automatically apply patches during installation.\n//    Add this entry to your 'scripts' object:\n/*\n\"scripts\": {\n  \"postinstall\": \"patch-package\"\n},\n*/\n//    If using Yarn v1, you must also install 'postinstall-postinstall' and use:\n//    \"postinstall\": \"postinstall-postinstall || patch-package\"\n\n// 4. Commit the generated patch file to your version control system (e.g., Git).\n//    The file will be located in a 'patches/' directory, named like 'patches/some-package+3.14.15.patch'.\n// git add patches/some-package+3.14.15.patch\n// git commit -m \"Fix brokenFile.js in some-package using patch-package\"\n\n// 5. From now on, any 'npm install' or 'yarn install' will automatically apply your patch.","lang":"javascript","description":"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."},"warnings":[{"fix":"Re-generate existing patch files using `patch-package` on version 8 to ensure they adhere to current naming conventions.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"For Yarn 2+ or pnpm projects, utilize their built-in patching mechanisms (`yarn patch` / `pnpm patch`) instead of `patch-package`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set the environment variable `NPM_CONFIG_PRODUCTION=false` or `YARN_PRODUCTION=false` in your Heroku application settings to ensure `postinstall` scripts run.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Command failed: patch-package Cannot run in wd /app"},{"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.","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`.","error":"Error: No patch file found for <package-name>@<version>"},{"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.","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.","error":"The patch file was for version x.y.z but the package is version a.b.c."}],"ecosystem":"npm"}