--- description: Learn how to apply small changes to a Capacitor plugin without forking or maintaining the entire plugin using the npm package patch-package. title: How to patch a Capacitor plugin - Capawesome image: https://capawesome.io/docs/assets/images/social/blog/how-to-patch-a-capacitor-plugin.png --- [Skip to content ](#how-to-patch-a-capacitor-plugin) [🖥️ Introducing the **Capacitor Electron Platform** — build desktop apps for macOS, Windows, and Linux. Free & open source. ](/blog/announcing-the-capacitor-electron-platform/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ Related Posts ](#related-posts) * [ Conclusion ](#conclusion) # How to patch a Capacitor plugin[¶](#how-to-patch-a-capacitor-plugin "Permanent link") Learn how to apply small changes to a Capacitor plugin without forking or maintaining the entire plugin. This is especially helpful when you need a hotfix for a plugin that isn't yet available in the official version, or when you need to make quick adjustments to accommodate your specific project requirements. In this guide, we'll use the npm package [patch-package](https://github.com/ds300/patch-package) by [David Sheldrick](https://github.com/ds300). > `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. 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. ## Getting Started[¶](#getting-started "Permanent link") First, install `patch-package` as a development dependency: `[](#%5F%5Fcodelineno-0-1)npm install --save-dev patch-package ` Next, add the following script to your `package.json`: package.json `[](#%5F%5Fcodelineno-1-1){ [](#%5F%5Fcodelineno-1-2) "scripts": { [](#%5F%5Fcodelineno-1-3) "postinstall": "patch-package" [](#%5F%5Fcodelineno-1-4) } [](#%5F%5Fcodelineno-1-5)} ` 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[¶](#creating-a-patch "Permanent link") 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`: | node\_modules/@capacitor-firebase/crashlytics/CapacitorFirebaseCrashlytics.podspec | | | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | [1](#%5F%5Fcodelineno-2-1) [2](#%5F%5Fcodelineno-2-2) | \- 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: `[](#%5F%5Fcodelineno-3-1)npx patch-package ` Replace `` 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: | patches/@capacitor-firebase+crashlytics+5.1.0.patch | | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [ 1](#%5F%5Fcodelineno-4-1) [ 2](#%5F%5Fcodelineno-4-2) [ 3](#%5F%5Fcodelineno-4-3) [ 4](#%5F%5Fcodelineno-4-4) [ 5](#%5F%5Fcodelineno-4-5) [ 6](#%5F%5Fcodelineno-4-6) [ 7](#%5F%5Fcodelineno-4-7) [ 8](#%5F%5Fcodelineno-4-8) [ 9](#%5F%5Fcodelineno-4-9) [10](#%5F%5Fcodelineno-4-10) [11](#%5F%5Fcodelineno-4-11) [12](#%5F%5Fcodelineno-4-12) [13](#%5F%5Fcodelineno-4-13) | 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[¶](#faq "Permanent link") ### Is patching a plugin always legally safe to do?[¶](#is-patching-a-plugin-always-legally-safe-to-do "Permanent link") 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?[¶](#what-happens-to-my-patch-when-the-plugin-releases-a-new-version "Permanent link") It may stop applying cleanly, or apply to the wrong lines. A patch is generated against a specific version's source, so upgrading the patched dependency means reviewing whether the patch still applies correctly — this is exactly why the guide calls out reviewing patches after every update as a required habit, not an optional nicety. ### Do teammates need to run any extra command to get my patch applied?[¶](#do-teammates-need-to-run-any-extra-command-to-get-my-patch-applied "Permanent link") 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?[¶](#should-i-use-patch-package-for-a-large-rewrite-of-a-plugins-internals "Permanent link") No — that's explicitly the wrong tool for the job here. Patches are meant for small, targeted fixes; for extensive modifications, maintaining a full fork is the better-scoped approach, 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?[¶](#if-my-patch-fixes-a-real-bug-should-i-keep-it-as-a-private-patch-indefinitely "Permanent link") 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[¶](#related-posts "Permanent link") * [How to Fix Capacitor Plugin Build Errors with AGP 9](/blog/how-to-fix-capacitor-plugin-build-errors-with-agp-9/) * [The Android Troubleshooting Guide for Capacitor](/blog/troubleshooting-capacitor-android-issues/) * [The iOS Troubleshooting Guide for Capacitor](/blog/troubleshooting-capacitor-ios-issues/) ## Conclusion[¶](#conclusion "Permanent link") `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. July 17, 2026 Back to top ```json { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "How to patch a Capacitor plugin", "description": "Learn how to apply small changes to a Capacitor plugin without forking or maintaining the entire plugin using the npm package patch-package.", "image": "https://capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png", "datePublished": "2023-12-06T00:00:00+00:00", "dateModified": "2026-07-17T00:00:00+00:00", "author": [ { "@type": "Person", "name": "Robin Genz", "url": "https://github.com/robingenz" } ], "publisher": { "@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": { "@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg" } }, "articleSection": "Capacitor", "keywords": ["Capacitor", "Guides", "SDKs"], "isPartOf": { "@type": "Blog", "@id": "https://capawesome.io/blog/#blog" }, "mainEntityOfPage": "https://capawesome.io/blog/how-to-patch-a-capacitor-plugin/", "url": "https://capawesome.io/blog/how-to-patch-a-capacitor-plugin/" } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://capawesome.io/" }, { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://capawesome.io/blog/" }, { "@type": "ListItem", "position": 3, "name": "How to patch a Capacitor plugin", "item": "https://capawesome.io/blog/how-to-patch-a-capacitor-plugin/" } ] } {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "Is patching a plugin always legally safe to do?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "What happens to my patch when the plugin releases a new version?", "acceptedAnswer": {"@type": "Answer", "text": "It may stop applying cleanly, or apply to the wrong lines. A patch is generated against a specific version's source, so upgrading the patched dependency means reviewing whether the patch still applies correctly — this is exactly why the guide calls out reviewing patches after every update as a required habit, not an optional nicety."}}, {"@type": "Question", "name": "Do teammates need to run any extra command to get my patch applied?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "Should I use patch-package for a large rewrite of a plugin's internals?", "acceptedAnswer": {"@type": "Answer", "text": "No — that's explicitly the wrong tool for the job here. Patches are meant for small, targeted fixes; for extensive modifications, maintaining a full fork is the better-scoped approach, 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."}}, {"@type": "Question", "name": "If my patch fixes a real bug, should I keep it as a private patch indefinitely?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}], "url": "https://capawesome.io/blog/how-to-patch-a-capacitor-plugin/"} ```