---
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 to make quick adjustments to accommodate your specific project requirements.

<!-- 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. This approach gives you the flexibility to maintain customizations without the overhead of 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 ensures that all patches are automatically applied after each installation of npm dependencies, keeping your customizations in sync across your team and CI/CD environments.

## 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
    ```

That's it! Commit the patch file to your repository and share it with your team. The patch will be automatically applied 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. This is worth checking 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 — there's no separate step teammates or CI need 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

`patch-package` is an invaluable tool for quickly applying small changes to your npm dependencies, making it especially useful in Capacitor projects where you need to maintain compatibility or apply urgent fixes.

Keep in mind a few best practices:

- **Review patches after updates**: When updating a patched dependency, review and update your patches as needed to ensure they still apply correctly.
- **Limit patch scope**: Avoid using patches for extensive modifications. For larger changes, consider maintaining a fork instead.
- **Contribute upstream**: Always report issues to the plugin maintainer and create a pull request when possible. This helps the entire community and may eliminate the need for your patch in future versions.

By following these guidelines, you can effectively use `patch-package` to keep your Capacitor projects running smoothly while contributing to the broader ecosystem.