---
title: How to Patch a Capacitor Plugin
description: Learn how to patch a Capacitor plugin with patch-package to apply small fixes without forking or maintaining the entire plugin yourself.
date:
  created: 2023-12-06
  updated: 2026-08-05
authors:
  - robingenz
categories:
  - Capacitor
  - Guides
  - SDKs
faq: true
---

# How to Patch a Capacitor Plugin

Learn how to patch a Capacitor plugin to apply small changes without forking or maintaining the entire plugin. This is especially helpful when you need a hotfix that isn't yet available in the official version, or when you need a small change that only your project requires.

<!-- more -->

## Key Takeaways

- **A patch is the lightweight alternative to a fork.** `patch-package` lets you change a Capacitor plugin's source code and keep that change without taking on the maintenance of a full fork.
- **One `postinstall` script keeps everyone in sync.** With `"postinstall": "patch-package"` in `package.json`, every patch is reapplied automatically after each `npm install` — for you, your team, and CI/CD.
- **Patches are generated per version.** Running `npx patch-package <package-name>` writes a file like `patches/@capacitor-firebase+crashlytics+5.1.0.patch`, so upgrading a patched dependency means reviewing whether the patch still applies.
- **Check the license before you patch.** Copyleft licenses such as GPL and MPL 2.0 can require you to publish your modifications.
- **Keep patches small and report fixes upstream.** For extensive modifications, maintain a fork instead — and file the issue with the plugin maintainer so you can eventually drop the patch entirely.

In this guide, we'll use the npm package [patch-package](https://github.com/ds300/patch-package){:target="_blank"} by [David Sheldrick](https://github.com/ds300){:target="_blank"}.

> `patch-package` lets app authors instantly make and keep fixes to npm dependencies. It's a vital band-aid for those of us living on the bleeding edge.

With `patch-package`, you can make changes to the source code of a plugin and create a patch that will be applied automatically whenever the plugin is installed. You keep your customizations without maintaining a complete fork.

!!! warning "Check the plugin license"

    Before modifying any plugin code, always review the plugin's license terms. Some open source licenses, such as GPL, MPL 2.0, and other copyleft licenses, require you to publish your modifications and may impose additional obligations on your project.

## Installing patch-package

First, install `patch-package` as a development dependency:

```bash
npm install --save-dev patch-package
```

Next, add the following script to your `package.json`:

```json title="package.json"
{
  "scripts": {
    "postinstall": "patch-package"
  }
}
```

This `postinstall` script reapplies all patches after each installation of npm dependencies, on your machine, on your teammates' machines, and in CI/CD.

## Creating a Patch for a Capacitor Plugin

To patch a Capacitor plugin, edit its source code in your `node_modules` folder and let `patch-package` turn those edits into a patch file. Follow these steps to create your first patch:

1. **Identify the issue**: Determine what you need to fix or modify. For example, you might need to resolve a compatibility issue with a specific version of a dependency.
2. **Make the necessary changes**: Modify the source code of the plugin directly in your `node_modules` folder.
   In this example, we'll change the version constraint of the `FirebaseCrashlytics` dependency from `10.8.0` to `>= 10.8.0`:
    ```diff title="node_modules/@capacitor-firebase/crashlytics/CapacitorFirebaseCrashlytics.podspec" linenums="1"
    -  s.dependency 'FirebaseCrashlytics', '10.8.0'
    +  s.dependency 'FirebaseCrashlytics', '>= 10.8.0'
    ```
3. **Generate the patch**: Once you've made your changes, generate the patch file by running:
    ```bash
    npx patch-package <package-name>
    ```
    Replace `<package-name>` with the npm package name of the plugin you want to patch (e.g., `@capacitor-firebase/crashlytics`).
    This command creates a new `patches` folder in your project root containing a patch file that looks something like this:
    ```diff title="patches/@capacitor-firebase+crashlytics+5.1.0.patch" linenums="1"
    diff --git a/node_modules/@capacitor-firebase/crashlytics/CapacitorFirebaseCrashlytics.podspec b/node_modules/@capacitor-firebase/crashlytics/CapacitorFirebaseCrashlytics.podspec
    index b7b17a9..ef91f1c 100644
    --- a/node_modules/@capacitor-firebase/crashlytics/CapacitorFirebaseCrashlytics.podspec
    +++ b/node_modules/@capacitor-firebase/crashlytics/CapacitorFirebaseCrashlytics.podspec
    @@ -13,7 +13,7 @@ Pod::Spec.new do |s|
    s.source_files = 'ios/Plugin/**/*.{swift,h,m,c,cc,mm,cpp}'
    s.ios.deployment_target  = '13.0'
    s.dependency 'Capacitor'
    -  s.dependency 'FirebaseCrashlytics', '10.8.0'
    +  s.dependency 'FirebaseCrashlytics', '>= 10.8.0'
    s.swift_version = '5.1'
    s.static_framework = true
    end
    ```

Commit the patch file to your repository and share it with your team. `patch-package` then applies the patch whenever anyone runs `npm install`.

## FAQ

### Is patching a plugin always legally safe to do?

No. Check the license first. Copyleft licenses like GPL and MPL 2.0 can require you to publish your modifications or impose other obligations, so a patch that seems like a quick private fix might carry disclosure requirements you didn't expect. Read the license before you write the patch, not after you've already shipped it.

### What happens to my patch when the plugin releases a new version?

It may stop applying cleanly, or apply to the wrong lines. A `patch-package` patch is generated against one specific version of a package's source, so upgrading a patched dependency means reviewing the patch and regenerating it if needed. Make that review a fixed step in every dependency upgrade rather than an afterthought.

### Do teammates need to run any extra command to get my patch applied?

No, as long as the `postinstall` script is committed. Once `patch-package` is wired into `package.json`'s `postinstall` hook and the patch file is committed to the repo, running a normal `npm install` automatically applies it. Teammates and CI have no separate step to remember.

### Should I use patch-package for a large rewrite of a plugin's internals?

No. `patch-package` is the wrong tool for a large rewrite. Patches are meant for small, targeted fixes; for extensive modifications, maintaining a full fork is better scoped, since a large patch is harder to review, more likely to break on the plugin's next release, and defeats the point of staying close to the upstream package.

### If my patch fixes a real bug, should I keep it as a private patch indefinitely?

Reporting it upstream is the better long-term move. Filing the issue with the plugin maintainer (and opening a pull request where possible) means the fix can land in a real release, which benefits everyone using the plugin and eventually lets you drop your local patch entirely instead of maintaining it release after release.

## Related Posts

- [How to Fix Capacitor Plugin Build Errors with AGP 9](./how-to-fix-capacitor-plugin-build-errors-with-agp-9.md)
- [The Android Troubleshooting Guide for Capacitor](./troubleshooting-capacitor-android-issues.md)
- [The iOS Troubleshooting Guide for Capacitor](./troubleshooting-capacitor-ios-issues.md)

## Conclusion

Reach for `patch-package` when the fix is a few lines and you need it before the plugin's next release. If the patch grows beyond that, or you have to regenerate it on every dependency upgrade, maintain a fork instead.

Either way, file an issue with the plugin maintainer and open a pull request where you can. Once the fix ships upstream, delete the patch file.