How to patch a Capacitor plugin

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 by David Sheldrick.

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

First, install patch-package as a development dependency:

npm install --save-dev patch-package

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

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

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:

   -  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:

   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 --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.

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.