--- description: Learn how to patch a Capacitor plugin with patch-package to apply small fixes without forking or maintaining the entire plugin yourself. 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 **Build Sharing** — get your builds onto testers' devices with a link & QR code. No account required. ](/blog/share-mobile-app-builds-with-testers/) * [ 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/) * [ Set Up 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/) * Notifications * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Network Restrictions ](/docs/cloud/organizations/network-restrictions/) * [ 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 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. ## Key Takeaways[¶](#key-takeaways "Permanent link") * **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 ` 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) 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. ## Installing patch-package[¶](#installing-patch-package "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 for a Capacitor Plugin[¶](#creating-a-patch-for-a-capacitor-plugin "Permanent link") 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`: | 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-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?[¶](#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 — `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?[¶](#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. August 5, 2026 Back to top ```json { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "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.", "image": "https://capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png", "datePublished": "2023-12-06T00:00:00+00:00", "dateModified": "2026-08-05T00: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-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."}}, {"@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 — 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."}}, {"@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/"} ```