# patch-package — Fix Broken Node Modules Instantly

> A tool that lets you make fixes to npm dependencies and keep those fixes in your repo as patch files, surviving reinstalls and CI builds without forking packages.

## Install

Save in your project root:

# patch-package — Fix Broken Node Modules Instantly

## Quick Use
```bash
npx patch-package some-package
```
Add to `package.json` scripts:
```json
"scripts": {
  "postinstall": "patch-package"
}
```

## Introduction
patch-package lets you fix bugs in your node_modules dependencies without waiting for upstream maintainers to merge and release a fix. You edit the dependency code directly in node_modules, run `npx patch-package <package-name>`, and it generates a `.patch` file that gets committed to your repo. On every `npm install` or `yarn install`, the postinstall script re-applies your patches automatically.

## What patch-package Does
- Generates git-style diff patches from your modifications to node_modules packages
- Stores patches in a `patches/` directory that you commit to version control
- Re-applies patches automatically via a postinstall hook after every install
- Supports scoped packages, nested dependencies, and monorepo setups
- Validates that patches apply cleanly and warns when they become stale

## Architecture Overview
When you run `patch-package <pkg>`, it compares your modified node_modules copy against the original package tarball from the npm registry. It produces a unified diff file stored at `patches/<pkg>+<version>.patch`. The postinstall command reads all `.patch` files from the patches directory and applies them using a built-in patch application engine. If a patch fails to apply (e.g., after a version bump), it exits with a clear error message indicating which hunk failed.

## Self-Hosting & Configuration
- Install as a dev dependency with `npm install -D patch-package`
- Add `"postinstall": "patch-package"` to your package.json scripts
- Edit the broken code directly in `node_modules/<package>/`
- Run `npx patch-package <package-name>` to generate the patch file
- Commit the `patches/` directory to your repository

## Key Features
- Works with npm, yarn, and pnpm package managers
- Supports patching nested dependencies via `--include-paths`
- Handles scoped packages like `@scope/package-name`
- Reverse patches with `--reverse` for debugging
- Provides clear error messages when patches become outdated after version upgrades

## Comparison with Similar Tools
- **yarn resolutions / npm overrides** — can pin or replace package versions but cannot modify source code
- **Forking on GitHub** — full control but adds maintenance burden and slows updates; patches are lighter
- **pnpm patch** — pnpm's built-in patch command inspired by patch-package; similar workflow
- **git submodules** — heavy-handed for small fixes; patch-package keeps changes as simple diffs

## FAQ
**Q: What happens when I upgrade the patched dependency?**
A: patch-package warns you that the patch was created for a different version. If the code changed in the patched area, you'll need to regenerate the patch.

**Q: Does it work in CI environments?**
A: Yes. The postinstall script runs automatically after `npm install` in CI. If a patch fails to apply, the build fails with a descriptive error.

**Q: Can I patch a transitive (nested) dependency?**
A: Yes. Use the `--include-paths` flag or navigate into the nested package path and run patch-package with the full path.

**Q: Is there a size limit for patches?**
A: No hard limit. Patches are plain text diffs, typically a few KB. Very large patches may indicate you should fork instead.

## Sources
- https://github.com/ds300/patch-package
- https://www.npmjs.com/package/patch-package

---
Source: https://tokrepo.com/en/workflows/asset-fb89a156
Author: AI Open Source