patch-package
Lets you fix npm dependencies in place and keep those fixes in version control.
- Stars
- 11.2k
- Forks
- 327
- Licence
- MIT
- Language
- TypeScript
- Last update
- 1.1 years ago
- Type
- Dev tool
No commits in over a year — check for forks or alternatives before adopting.
What it is
patch-package is a Node.js tool that lets you edit a file inside a dependency in node_modules, then saves the change as a .patch file. You commit that file to your project, and it is re-applied automatically when npm or yarn installs packages, so your team gets the same fix without waiting for the upstream maintainer to release one.
- Edit a broken file in node_modules, run npx patch-package <name>, and commit the generated patch to share the fix
- Add a second patch to the same package using --append, with patches ordered like commits
- Reverse all patches with --reverse when troubleshooting caching issues in CI
Great for
- Teams running a Node.js app who need a quick fix to a dependency before the upstream project publishes one
- Developers on npm 5 or later, or yarn v1, who want patches applied on every install
- Projects that want to avoid forking a dependency just to change one file
Not ideal for
- Projects on yarn v2+ or pnpm, which the README says have native patching support (yarn patch, pnpm patch), so patch-package is not needed there
- Deployments that install production-only dependencies, unless you follow the dev-only patch steps, because patches to devDependencies may be skipped or throw errors
- Anyone wanting a permanent replacement for contributing a fix upstream; the README presents it as a band-aid
How to get it
- 1
Install with a package manager
You'll need: Node.js with npm 5 or later, or yarn v1
Add the postinstall script to package.json (edit file)
"postinstall": "patch-package"Install with npm
npm i patch-packageInstall with yarn v1
yarn add patch-package postinstall-postinstall - 2
Run it
- Add the postinstall script to the scripts section of package.json
- Install patch-package with npm or yarn
- Edit a file inside node_modules/<package-name>
- Run npx patch-package <package-name> to create the patch file in the patches folder
- Commit the patch file to share it with your team
- 3
Get the most out of it
- Use --include and --exclude regexps to control which files go into a patch
- Use --create-issue to open a draft GitHub issue from your diff for packages hosted on GitHub
- Use --error-on-fail to make CI fail when a patch cannot be applied (it is on by default on CI according to the README)
- Use the --append and --rebase options to manage multiple ordered patches for one package
- Rename patches to .dev.patch for transitive devDependencies in production builds
Downloads
Strengths
- Fixes can be applied immediately without waiting for a dependency release
- Patch files are plain text diffs stored in the repo, so they are easy to review in git
- Applies automatically through a postinstall script with npm or yarn v1
Trade-offs
- The README describes it as a band-aid, and patches can fail if the patched dependency changes, requiring manual rework
- Needs extra setup for Heroku, Docker, and CI caching, as the README details
- Dev-only and transitive dependency cases add complexity
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| patch-package (this) | 11.2k | Dev tool | beginner | 1.1 years ago | Teams running a Node.js app who need a quick fix to a dependency before the upstream project publishes one |
| pnpm | 37k | Dev tool | beginner | 4 days ago | Developers working in Node.js projects who want faster installs and less disk use |
| nvm | 95.7k | Dev tool | beginner | 9 days ago | Developers who work on several Node.js projects that need different versions |
| poetry | 34.3k | Dev tool | intermediate | 5 days ago | Python developers starting a new project who want one config file for dependencies and packaging |
| composer | 29.6k | Dev tool | beginner | 4 days ago | PHP developers starting a new project who want standard third-party libraries |
| nvm | 48.1k | App | beginner | 4 days ago | Windows developers who work on several Node.js projects that need different versions |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.