Capacitor 4 is out 🎉
https://ionicframework.com/blog/announcing-capacitor-4-0/
In practice, whether you can upgrade your project to Capacitor 4 right away depends on whether the Capacitor plugins you use support it—you may need to investigate and update them. Here is a short guide to that process.
How to check Capacitor 4 support
The check itself is easy: open the repository package.json and look at @capacitor/core and related versions.
"devDependencies": {
"@capacitor/android": "^3.0.0",
"@capacitor/core": "^3.0.0",
If you see ^3.0.0, it is a Capacitor 3 plugin. When v4 support is done, it looks like this.
"devDependencies": {
"@capacitor/android": "^4.0.0",
"@capacitor/core": "^4.0.0",
Tricky cases use next or latest as the version. Recent plugins rarely do this, but if they do, check whether the repo was updated on or after July 31, 2022—that is usually enough. If it is still unclear, look at package-lock.json.
If v4 support is done, upgrading is simple: install the latest version of that plugin. v4 is still new, so many authors—including me—publish Capacitor 4 builds as pre-releases. Then npm install plugin-name@latest may not install the v4 build.
https://github.com/capacitor-community/stripe/releases
Check release notes; if v4 support is a pre-release, install with npm install plugin-name@next.
Updating a plugin that does not support Capacitor 4 yet
If the plugin is not on v4 yet, you can wait for the author—or why not open a pull request? Here is a quick path to verify and contribute.
1. Fork and clone
Fork the repository and clone it locally. I will skip the usual Git steps here.
2. Upgrade and npm install
In a terminal, cd into the cloned folder and run:
% npx @rdlabo/capacitor-plugin-to-v4
% npm install
If the plugin follows the default Capacitor plugin layout, that alone completes the upgrade 🎉
3. Link to your project with npm link
npm lets you link a local package to your project with npm link. First, in the plugin project:
% npm link
Then, in your Capacitor project that uses the plugin—for example, when updating @capacitor-community/hoge:
% npm link @capacitor-community/hoge
Your project now resolves the local upgraded plugin.
4. Verify in your Capacitor project
Test it. If you have not upgraded your Capacitor project to Capacitor 4 yet, run this first:
% npm install @capacitor/cli
% npx cap migrate
A common pitfall right after upgrading: on Android, Android Studio's Java version may not match Capacitor 4.
https://capacitorjs.com/docs/updating/4-0#ensure-you-are-using-java-11
Do not forget to set Gradle JDK to Java 11.
5. Open a pull request
Does it work? If the plugin behaves after exercising it, open a pull request. Well done!
Troubleshooting
Errors from outdated libraries the plugin uses
On iOS, library versions are set in the plugin folder's (plugin-name).podspec and ios/Podfile.
Examples: https://github.com/capacitor-community/stripe/blob/master/CapacitorCommunityStripe.podspec#L16 https://github.com/capacitor-community/stripe/blob/master/ios/Podfile#L8
On Android, see android/build.gradle in the plugin folder.
Example: https://github.com/capacitor-community/stripe/blob/master/android/build.gradle#L62-L65
Bump those versions to fix the issue.
Android cannot install libraries
Check android/build.gradle in the plugin folder. If mavenCentral is not registered in both places below, add it.
https://github.com/capacitor-community/stripe/blob/master/android/build.gradle#L12 https://github.com/capacitor-community/stripe/blob/master/android/build.gradle#L50
Summary
Easy, right? If several plugins in your project lack Capacitor 4 support and all need updates, a fresh test project may make root-cause analysis easier.
Even if the pull request is never merged, while you are npm linked the Capacitor build succeeds, so you can ship to the app store as-is. Enjoy Capacitor 4!