# Patch-Package and why should use it

The **patch-package** npm package is a crucial tool for developers who need to quickly fix issues or apply custom changes to third-party npm dependencies when maintainers are slow to respond, or a fork is too heavy-handed. Here's a comprehensive guide for devs, focused on practical learning and use-cases.[npmjs+1](https://www.npmjs.com/package/patch-package)

## What is patch-package?

**patch-package** enables developers to make and preserve fixes directly to npm packages in node\_modules, recording changes as patch files. These patches can be version-controlled and automatically reapplied after every install, maintaining local fixes without needing to fork or wait for upstream updates.[dev+1](https://dev.to/andreasbergstrom/patch-package-the-essential-tool-for-managing-dependencies-in-both-modern-and-legacy-projects-4hnn)

## When and Why Should You Use patch-package?

* Resolve bugs in dependencies without waiting for maintainers to merge pull requests or publish releases.[dev](https://dev.to/andreasbergstrom/patch-package-the-essential-tool-for-managing-dependencies-in-both-modern-and-legacy-projects-4hnn)
    
* Apply project-specific tweaks or optimizations to npm packages, especially when your project's requirements differ.
    
* Address security vulnerabilities or compatibility issues in legacy or abandoned packages.
    
* Avoid the complexity and overhead of forking entire repositories for minor fixes.
    

## Real-World Scenario

Suppose a React Native dependency contains a bug impacting production. By modifying the code inside node\_modules and generating a patch, teams can deploy their fix while tracking it in version control—no waiting for external fixes or risky upgrades.[dev](https://dev.to/andreasbergstrom/patch-package-the-essential-tool-for-managing-dependencies-in-both-modern-and-legacy-projects-4hnn)

## Step-by-Step Usage Guide

1. **Edit the dependency code:**  
    Make the required change directly in the package folder inside `node_modules`, e.g., `node_modules/some-lib/index.js`.[npmjs](https://www.npmjs.com/package/patch-package)
    
2. **Generate a patch:**  
    Run `npx patch-package some-lib` (or `yarn patch-package some-lib`) to create a patch file in the `patches/` directory.[npmjs+1](https://www.npmjs.com/package/patch-package)
    
3. **Version control the patch:**  
    Commit the patch file—this ensures your fix persists across environments and installs.
    
4. **Apply patches automatically:**  
    Add `"postinstall": "patch-package"` to your `package.json` scripts to ensure patches are automatically reapplied after every `npm install` or `yarn install`.[dev](https://dev.to/andreasbergstrom/patch-package-the-essential-tool-for-managing-dependencies-in-both-modern-and-legacy-projects-4hnn)
    
5. **Maintain and update patches:**  
    Use advanced features like `--append` for multiple patches, or `--rebase` to update specific patches sequentially, emulating a mini git history for dependency fixes.[npmjs](https://www.npmjs.com/package/patch-package)
    

## Pro Tips

* Use `--exclude` and `--include` to fine-tune what gets included in a patch.
    
* For nested or scoped packages, reference them like `package/another-package` or `@scope/package`.[npmjs](https://www.npmjs.com/package/patch-package)
    

## Comparison: patch-package vs. Forcing Upgrades vs. Forking

| Method | Pros | Cons |
| --- | --- | --- |
| **patch-package** | Fast, minimal, version-controlled fixes [dev](https://dev.to/andreasbergstrom/patch-package-the-essential-tool-for-managing-dependencies-in-both-modern-and-legacy-projects-4hnn) | Needs patch update with dependency upgrades [dev](https://dev.to/andreasbergstrom/patch-package-the-essential-tool-for-managing-dependencies-in-both-modern-and-legacy-projects-4hnn) |
| Forking | Full control, independent releases | Maintenance overhead, merge conflicts |
| Forcing Upgrades | Follows official fixes/releases | Risk of breaking changes, delayed fixes |