--- title: 'Patching NPM Dependencies with pnpm patch' date: 2025-11-11 updated: 2026-06-23 excerpt: 'Learn how to patch NPM dependencies with pnpm patch to fix issues with your project.' tags: [javascript, oss, devtools] canonical: https://mikebifulco.com/posts/patching-npm-dependencies-with-pnpm-patch --- # Patching NPM Dependencies with pnpm patch > **TL;DR:** `pnpm patch ` lets you fix a broken dependency locally and keep the fix in version control. Edit the package in the temp directory pnpm opens, run `pnpm patch-commit `, and pnpm re-applies the patch on every install. No fork, and no waiting for the maintainer to ship a release. ## Introduction Sometimes a third-party package breaks, and you can't wait for a PR to make its way into a release. Fortunately, `pnpm patch` makes it dead simple to hotfix packages locally while keeping your version control clean. Recently, we needed to patch the [`@payloadcms/storage-uploadthing` package](https://www.npmjs.com/package/@payloadcms/storage-uploadthing) to fix a bug with image loading, so that we could continue to use it as our image hosting provider for [Craftwork](https://craftwork.com)'s implementation of [Payload CMS](https://payloadcms.com). Here's how we handled it, using `pnpm patch`. ### What is pnpm patch? [`pnpm patch`](https://pnpm.io/cli/patch) is a tool provided by the pnpm package manager that allows you to patch packages locally—and commit those changes cleanly. It works by creating a patch file that contains the changes you want to make to the package. You can then apply the patch file to the package using `pnpm install`. ## The process Patching a package is a three-step process: 1. Track down the bug 2. Create a patch file 3. Apply the patch file to the package Let's go through each step in detail. ### Step 1: Track down the bug In our case, we tracked the bug down by making changes to the `handleUpload` function in `@payloadcms/storage-uploadthing`. You can do this in two ways: 1. Dig into `node_modules/@payloadcms/storage-uploadthing/src/...` directly 2. Or, clone the repo and search from there if you want to keep your project folder clean We worked directly inside `node_modules` to validate the fix quickly. One thing to keep in mind here is that running `pnpm install` will overwrite your changes to the package -- which is eactly why we need to use `pnpm patch` to create a persistent patch! ### Step 2: Make a Local Fix Once you've got a fix in mind, try it out directly in your project. You will do this by making temporary edits right inside the installed version of the package within your IDE. > In our case, the fix for `@payloadcms/storage-uploadthing` involved some minor changes: > > - the `handleUpload` function wasn't setting a `url` field based on the UploadThing API's response, so our Payload db didn't have any image URLs stored. > - the `disablePayloadAccessControl` setting was commented out, which caused payload to store *local* image URLs instead of UploadThing's public URLs. Once we saw that this fix solved the issue in development, it was time to commit it to source control using `pnpm patch`. ### Step 3: Create a Persistent Patch with pnpm patch ![A screenshot of the terminal showing the output of the \`pnpm patch\` command](https://res.cloudinary.com/mikebifulco-com/image/upload/q_auto:eco,f_auto/v1/posts/patching-npm-dependencies-with-pnpm-patch/patch-process-1) *The \`pnpm patch\` command opens the dependency's code in a temporary directory for you to edit.* To preserve your fix and commit it to source control: 1. run: `pnpm patch `. This opens the dependency's code in a temporary directory for you to edit. 2. Reapply the fix in the temporary folder. 3. Test it - do everything you would typically do to make sure the fix works: test functionality, run linters and test suites, etc. 4. To complete your patch and ready it for addition to source control on your project, run: `pnpm patch-commit ` That saves the patch to your repo, and pnpm will re-apply it automatically every time you install dependencies. It also modifies your `package.json` to reference the patched version. This will add a new entry to your `package.json` like this: ```json "@payloadcms/storage-uploadthing": { "patches": { "@payloadcms/storage-uploadthing": "patch/@payloadcms/storage-uploadthing.patch" } } ``` ...as well as a file in your project's `patches` directory that represents the patch itself, in git diff format. This file type is a little difficult to read. You can re-open your patch file in your code editor to see the changes. Your changes will also be reflected in your `pnpm-lock.yaml` file. This will cause pnpm to apply the patch every time you install dependencies. ### If you need to edit your patch This is one part of the workflow that leaves a bit to be desired - if you need to edit your patch later, the best workflow I've found is to remove the patch from your project by running: `pnpm patch-remove `, and then start a fresh patch by running: `pnpm patch ` (and going through these steps again). You *can* edit the `.patch` file directly, but it's finicky. In most cases, it's easier to remove and re-create the patch. ### Closing the loop with the package maintainer Your dependency is now patched, and you can commit it to source control to use. This can help provide evidence to open source maintainers that the fix is needed, and that it works. It's good practice to [open a pull request](https://github.com/payloadcms/payload/pull/14250) to the package maintainer with your fix so that they can review it and merge it into the main branch. ### When it's time to remove the patch Once there is an upstream fix in place, you can remove the patch from your project by running: `pnpm patch-remove `. This will remove the patch from your `package.json` and the `patches` directory, and you can then commit the changes to source control. Remember that this doesn't automatically update the dependency in your project to the latest version - you'll still need to use `pnpm install` to do that. --- ## Why this process is useful - You don't need to wait on library maintainers to merge PRs to get your fix into your project - Your fix lives in version control, so teammates and CI builds stay in sync - It's a fast, repeatable way to patch packages without publishing a fork ## Not using pnpm? If your team is using a package manager other than pnpm, there are other options that are very similar: - for `yarn` you can use [`yarn patch`](https://yarnpkg.com/cli/patch) - for `bun` you can use [`bun patch`](https://bun.com/docs/pm/cli/patch) - for `npm` you can use [`npx patch package`](https://www.npmjs.com/package/patch-package) - if you're using ruby's `bundler`, you're in the wrong place, and you have my sympathies. The specifics of each of these options are very similar, but vary slightly - refer to the docs linked above for a walkthrough of each. ## FAQ ### What is pnpm patch? `pnpm patch` is a command built into the pnpm package manager that lets you make local changes to an installed dependency and save them as a patch file. pnpm re-applies that patch automatically on every `pnpm install`, so your fix survives reinstalls without maintaining a fork. ### Where does pnpm store the patch file? In a `patches/` directory at the root of your project, as a `.patch` file in git-diff format. pnpm also adds a reference to it in your `package.json` and your `pnpm-lock.yaml`, so the patch is committed to source control alongside the rest of your project. ### How do I edit an existing pnpm patch? The cleanest workflow is to remove the patch with `pnpm patch-remove ` and then start fresh with `pnpm patch `. You *can* edit the `.patch` file by hand, but it's finicky; removing and re-creating is usually faster. ### How do I remove a pnpm patch when there's an upstream fix? Run `pnpm patch-remove `, which clears the entry from your `package.json` and the `patches/` directory. Note that this does **not** bump the dependency. Run `pnpm install` to actually move to the version that contains the upstream fix. ### Can I patch dependencies without pnpm? Yes. Yarn has [`yarn patch`](https://yarnpkg.com/cli/patch), Bun has [`bun patch`](https://bun.com/docs/pm/cli/patch), and for npm you can use [`patch-package`](https://www.npmjs.com/package/patch-package). The workflows are very similar in spirit. ## More from mikebifulco.com - [Contributing to Open Source without being a Jerk](https://mikebifulco.com/newsletter/open-source-is-community) - [Open Source your learning with GitHub](https://mikebifulco.com/newsletter/open-source-is-your-secret-weapon) - [The first year of being a technical startup cofounder](https://mikebifulco.com/newsletter/reflecting-on-one-year-as-startup-cto) --- Written by Mike Bifulco. Originally published at https://mikebifulco.com/posts/patching-npm-dependencies-with-pnpm-patch