Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add v3 to v4 plugin migration page #123

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion docs/main/updating/4-0.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@ post_install do |installer|
end
```

Additionally, update the `podspec` file at the root of the project:

```
s.ios.deployment_target = '13.0'
```

### Remove Unnecessary Code

Remove unused `touchesBegan` method from `AppDelegate.swift`
Expand Down Expand Up @@ -280,4 +286,4 @@ The `@capacitor/storage` plugin has been renamed to `@capacitor/preferences` to

### Splash Screen

- If switching to the new Android 12 Splash Screen API, most configuration options won't be available for the initial Splash Screen, but they will still be available for the Splash Screen that appears when calling `show()`. Also, on Android 12+ devices the initial Splash Screen is different from the Splash Screen shown by `show()` method.
- If switching to the new Android 12 Splash Screen API, most configuration options won't be available for the initial Splash Screen, but they will still be available for the Splash Screen that appears when calling `show()`. Also, on Android 12+ devices the initial Splash Screen is different from the Splash Screen shown by `show()` method.
228 changes: 0 additions & 228 deletions docs/main/updating/plugins/3-0.md

This file was deleted.

77 changes: 77 additions & 0 deletions docs/main/updating/plugins/4-0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
---
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
Copy link
Contributor Author

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?


### Update Android Project Variables

In your `build.gradle` file, update your values to the following new minimums:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In your `build.gradle` file, update your values to the following new minimums:
In your `android/build.gradle` file, update your values to the following new minimums:


```groovy
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 : instead of = )
So maybe instead of a code block use a list saying
minSdkVersion to 22
compileSdkVersion to 32
etc.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Adjust your Gradle project settings in `File > Project Structure > Project`. The Android Gradle Plugin Version should be 7.2.1 and the Gradle Version should be 7.4.2. Apply these changes and run a gradle sync by clicking on the Elephant Icon in the top right of Android Studio.

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!
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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!
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 `android/build.gradle` file. If you are using other native dependencies, make sure they aren't hosted on Jcenter before removing it!



## 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 follow these steps:

1. Update the iOS version to 13.0:

```ruby
platform :ios, '13.0'
```


2 changes: 1 addition & 1 deletion sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ module.exports = {
'main/updating/3-0',
'main/updating/2-0',
'main/updating/1-1',
'main/updating/plugins/3-0',
'main/updating/plugins/4-0',
],
},
{
Expand Down