explaingit

ds300/patch-package

★ 11,178TypeScriptAudience · developerComplexity · 2/5Setup · easy

TLDR

JavaScript tool that lets you directly fix bugs in your npm dependencies and saves those fixes as committed patch files that are automatically reapplied every time anyone runs npm install.

Mindmap

mindmap
  root((patch-package))
    What it does
      Patches node modules
      Commits .patch files
      Auto-applies on install
    Workflow
      Edit node module file
      Run patch-package
      Commit patch file
    Compatibility
      npm
      yarn v1
    Use Cases
      Bug workarounds
      CI deployments
      Docker builds
    Audience
      JavaScript developers
      Frontend teams
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Fix a bug in a third-party npm package today without waiting for the maintainer to release an official update.

USE CASE 2

Commit a .patch file so every teammate and CI machine automatically gets your dependency fix on the next install.

USE CASE 3

Apply temporary workarounds to node_modules packages in a Docker-deployed app without breaking the build cache.

Tech stack

TypeScriptNode.jsnpmyarn

Getting it running

Difficulty · easy Time to first run · 5min

Works with npm and yarn v1 only, yarn v2+, pnpm, and Bun have built-in patch commands and do not require this tool.

No license information stated in the explanation.

In plain English

patch-package is a tool for JavaScript and TypeScript projects that lets you make fixes to third-party packages in your node_modules folder and keep those fixes across installs. When a dependency has a bug, you normally have to wait for the maintainer to release a fix and then update your version. With patch-package, you edit the broken file directly inside node_modules, run a single command, and it creates a .patch file that records your changes. That patch file gets committed to your repository and is automatically reapplied whenever anyone runs npm install or yarn install. The workflow is simple: find the broken file inside node_modules, edit it, run npx patch-package package-name, then commit the resulting .patch file. Anyone who clones your project and installs dependencies will get your fix applied automatically. The setup is a one-time addition to your package.json scripts, adding a postinstall step that runs patch-package after every install. It works with npm and yarn v1. Yarn v2 and newer, as well as pnpm, have built-in patching features and do not require this tool. For projects deployed to servers or run inside containers, the README covers extra steps to make sure patches apply correctly, including how to handle caching in CI systems like CircleCI without accidentally skipping a patch update. The tool also handles less common scenarios: patching packages nested inside other packages, marking patches as dev-only so they are safely skipped in production environments, and creating multiple patch files for the same package. You can also apply or reverse patches manually using the patch-dir option or standard Unix tools. The project has over 11,000 stars and addresses a very common frustration in JavaScript development. It does not replace contributing fixes upstream or keeping your dependencies maintained, but it gives you a practical way to keep your project working while you wait for an official resolution.

Copy-paste prompts

Prompt 1
A package in my node_modules has a bug. Walk me through using patch-package to fix the file, create the patch, and commit it so teammates get the fix automatically on install.
Prompt 2
Add patch-package to my existing React app, show me the one-time setup change to package.json and the postinstall script I need.
Prompt 3
I use CircleCI and I'm worried my patch won't apply because of caching. Show me how to configure CircleCI so patch-package always runs correctly after install.
Prompt 4
How do I create a dev-only patch with patch-package so the fix applies in development but is safely skipped in production?
Prompt 5
I need to patch a package that is nested inside another package in my node_modules. How does patch-package handle that case?
Open on GitHub → Explain another repo

← ds300 on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.