Add v3 to v4 plugin migration page #123
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,79 @@ | ||||||
| --- | ||||||
| title: Updating plugins to 4.0 | ||||||
| description: Guide for updating a Capacitor v3 plugin to v4 | ||||||
| slug: /updating/plugins/4-0 | ||||||
| --- | ||||||
|
|
||||||
| # Updating a Capacitor v3 plugin to 4.0 | ||||||
|
|
||||||
| There are only a few changes required to update a plugin from Capacitor 3 to Capacitor 4. | ||||||
|
|
||||||
| :::info | ||||||
| While you can follow the manual steps below, check out [this tool](https://github.com/rdlabo-team/capacitor-plugin-to-v4) from community member [@rdlabo](https://twitter.com/rdlabo) that automatically updates a Capacitor 3 plugin to v4. | ||||||
| ::: | ||||||
|
|
||||||
| ## Android | ||||||
|
|
||||||
| ### Update Android Project Variables | ||||||
|
|
||||||
| In your `build.gradle` file, update your values to the following new minimums: | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ```groovy | ||||||
|
There was a problem hiding this comment. this block is confusing, looks like you copied the changes from the variables.gradle file, but in plugins there is no variables.gradle file and the values are in different places and with a different format (using |
||||||
| minSdkVersion = 22 | ||||||
| compileSdkVersion = 32 | ||||||
| targetSdkVersion = 32 | ||||||
| androidxAppCompatVersion = '1.4.2' | ||||||
| junitVersion = '4.13.2' | ||||||
| androidxJunitVersion = '1.1.3' | ||||||
| androidxEspressoCoreVersion = '3.4.0' | ||||||
| ``` | ||||||
|
|
||||||
| ### Update to Gradle 7 | ||||||
|
|
||||||
| Adjust your Gradle project settings in `File > Project Structure > Project`. The Android Gradle Plugin Version should be 7.2.1 or later and the Gradle Version should be 7.4.2 or later. Apply these changes and run a gradle sync by clicking on the Elephant Icon in the top right of Android Studio. | ||||||
|
There was a problem hiding this comment.
Suggested change
Better not use "or later" as newer versions could cause issues, stick to the ones we used in all plugins and Capacitor itself. |
||||||
|
|
||||||
| :::info | ||||||
| Android Studio may provide an automatic migration to Gradle 7. Go ahead and take them up on the offer! To upgrade, go to your `build.gradle` file, and click on the 💡 icon, and click "Upgrade Gradle. Once your project is migrated over, run a gradle sync as described above. | ||||||
|
|
||||||
| Another alternative would be to use the Android Gradle Plugin Upgrade Assistant to handle the migration for you. Steps for this tool can be found in the [Android documentation](https://developer.android.com/studio/build/agp-upgrade-assistant). | ||||||
| ::: | ||||||
|
|
||||||
| ### Ensure you are using Java 11 | ||||||
|
|
||||||
| Capacitor 3 works with both Java 8 and Java 11. Moving forward, Capacitor 4 will only support Java 11. You can change this in your project by going to the following menu in Android Studio: | ||||||
|
|
||||||
| `Preferences > Build, Execution, Deployment > Build Tools > Gradle` | ||||||
|
|
||||||
| <img | ||||||
| src={require('/img/v4/docs/main/updating/android-java-11.png').default} | ||||||
| loading="eager" | ||||||
| /> | ||||||
|
|
||||||
| From there, you can modify the "Gradle JDK" to be Java 11. | ||||||
|
|
||||||
| :::info | ||||||
| Java 11 ships with the latest version of Android Studio. No additional downloads needed! | ||||||
| ::: | ||||||
|
|
||||||
| ### Remove `jcenter()` from the Gradle files | ||||||
|
|
||||||
| In previous Capacitor versions, `jcenter()` was required due to our Cordova compatibility layer being hosted on Jcenter. However, we are now using the latest Cordova Android version, hosted on Maven Central. With this, you may be able to remove `jcenter()` entirely from your `build.gradle` file. If you are using other native dependencies, make sure they aren't hosted on Jcenter before removing it! | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
|
|
||||||
| ## iOS | ||||||
|
|
||||||
| ### Raise iOS Deployment Target | ||||||
|
|
||||||
| Do the following to your Xcode project: select the **Project** within the project editor and open the **Build Settings** tab. Under the **Deployment** section, change **iOS Deployment Target** to **iOS 13.0**. Repeat the same steps for any app **Targets**. | ||||||
|
|
||||||
| Then, open `ios/App/Podfile` and update the iOS version to 13.0: | ||||||
|
There was a problem hiding this comment.
Suggested change
The guide is about plugins, there is no App folder in plugins, the Podfile is inside the ios folder |
||||||
|
|
||||||
| ```ruby | ||||||
| platform :ios, '13.0' | ||||||
| ``` | ||||||
|
|
||||||
| Next, update the `podspec` file at the root of the project: | ||||||
|
|
||||||
| ``` | ||||||
| s.ios.deployment_target = '13.0' | ||||||
| ``` | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I followed this commit to figure out what changed. I may have missed something. if it's easier, maybe we just recommend the migration tool?