Updating Capacitor to 2.0 in your app
Capacitor 2 makes some tooling updates including the adoption of Swift 5 in iOS and AndroidX for Android.
Read the Capacitor 2.0 announcement โบ
Update Capacitor dependencies
First, update Capacitor Core and the CLI:
npm install @capacitor/cli@2 @capacitor/core@2
Next, update each Capacitor platform that you use:
# iOS
npm install @capacitor/ios@2
npx cap sync ios
# Android
npm install @capacitor/android@2
npx cap sync android
# Electron
cd electron
npm install @capacitor/electron@2
Backward Incompatible Plugin Changes
- Camera
saveToGallery
default value is nowfalse
on all platforms- if
allowEditing
istrue
and the edit is canceled, the original image is returned
- Push Notifications
- permissions will no longer be requested when
register()
is called, userequestPermission()
PushNotificationChannel
renamed toNotificationChannel
- permissions will no longer be requested when
- Local Notifications
- permissions will no longer be requested when
register()
is called, userequestPermission()
schedule()
now returnsLocalNotificationScheduleResult
- permissions will no longer be requested when
- Toast
- unify duration across platforms: short 2000ms, long 3500ms
- Geolocation
- use Fused Location Provider on Android
requireAltitude
removed fromGeolocationOptions
- change native location accuracy values on iOS (more info)
- Filesystem
createIntermediateDirectories
was removed fromMkdirOptions
(userecursive
instead)recursive
option added to writeFile, which changes behavior on Android and web (more info)Application
directory option removed because it was broken
- Device
batteryLevel
andisCharging
removed fromgetInfo()
, usegetBatteryInfo()
- Modals
inputPlaceholder
sets a placeholder instead of text, useinputText
instead
- App
AppRestoredResult
is optional now, returned only if succeeded, otherwise it returns an error
- Clipboard
ReadOptions
was removed
iOS
Capacitor 2 requires Xcode 11+.
Update native project to Swift 5
Capacitor 2 uses Swift 5. It's recommended to update your native project to also use Swift 5.
- From Xcode click Edit -> Convert -> To Current Swift Syntax.
- App.app will appear selected, click Next button.
- Then a message will say No source changes necessary.
- Finally, click the Update button.
Android
AndroidX
Capacitor 2 uses AndroidX for Android support library dependencies as recommended by Google, so the native project needs to be updated to use AndroidX as well.
From Android Studio do Refactor -> Migrate to AndroidX. Then click on Migrate button and finally click on Do Refactor.
If using Cordova or Capacitor plugins that don't use AndroidX yet, you can use jetifier tool to patch them.
npm install jetifier
npx jetifier
To run it automatically after every package install, add "postinstall": "jetifier"
in the package.json
.
Create common variables
Create a android/variables.gradle
file with this content:
ext {
minSdkVersion = 21
compileSdkVersion = 29
targetSdkVersion = 29
androidxAppCompatVersion = '1.1.0'
androidxCoreVersion = '1.2.0'
androidxMaterialVersion = '1.1.0-rc02'
androidxBrowserVersion = '1.2.0'
androidxLocalbroadcastmanagerVersion = '1.0.0'
firebaseMessagingVersion = '20.1.2'
playServicesLocationVersion = '17.0.0'
junitVersion = '4.12'
androidxJunitVersion = '1.1.1'
androidxEspressoCoreVersion = '3.2.0'
cordovaAndroidVersion = '7.0.0'
}
In android/build.gradle
file, add apply from: "variables.gradle"
:
classpath 'com.android.tools.build:gradle:4.1.1'
classpath 'com.google.gms:google-services:4.3.3'
// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
}
+apply from: "variables.gradle"
allprojects {
repositories {
google()
jcenter()
Use common variables
If you created the variables.gradle
file, update your project to use them.
In the android/app/build.gradle
file, make the following updates:
android {
- compileSdkVersion 28
+ compileSdkVersion rootProject.ext.compileSdkVersion
defaultConfig {
applicationId "com.example.app"
- minSdkVersion 21
- targetSdkVersion 28
+ minSdkVersion rootProject.ext.minSdkVersion
+ targetSdkVersion rootProject.ext.targetSdkVersion
versionCode 1
versionName "1.0"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
dependencies {
implementation fileTree(include: ['*.jar'], dir: 'libs')
- implementation 'androidx.appcompat:appcompat:1.0.0'
+ implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
implementation project(':capacitor-android')
- testImplementation 'junit:junit:4.12'
- androidTestImplementation 'androidx.test.ext:junit:1.1.1'
- androidTestImplementation 'androidx.test.espresso:espresso-core:3.1.0'
+ testImplementation "junit:junit:$junitVersion"
+ androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+ androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
implementation project(':capacitor-cordova-android-plugins')
Don't miss the change from single quotes to double quotes. Double quotes are required for variable interpolation.
Android Studio plugin update recommended
When you open the Android project in Android Studio, a Plugin Update Recommended message will appear. Click on update. It will tell you to update Gradle plugin and Gradle. Click Update button.
You can also manually update the Gradle plugin and Gradle.
To manually update Gradle plugin, in android/build.gradle
file, update the com.android.tool.build:gradle
version to 3.6.1.
To manually update Gradle, in android/gradle/wrapper/gradle-wrapper.properties
, change gradle-4.10.1-all.zip
to gradle-5.6.4-all.zip
.
Update Google Services plugin
In android/build.gradle
file, update the com.google.gms:google-services
dependency version to 4.3.3.
dependencies {
classpath 'com.android.tools.build:gradle:4.1.1'
- classpath 'com.google.gms:google-services:4.2.0'
+ classpath 'com.google.gms:google-services:4.3.3'
// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
Change android:configChanges
to avoid app restarts
In android/app/src/main/AndroidManifest.xml
, add |smallestScreenSize|screenLayout|uiMode
in the activity's android:configChanges
attribute.
<activity
- android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale"
+ android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode"
android:name="com.example.app"
android:label="@string/title_activity_main"
android:theme="@style/AppTheme.NoActionBarLaunch"
android:launchMode="singleTask">
Add caches folder to FileProvider
file paths to avoid permission error when editing gallery images
In android/app/src/main/res/xml/file_paths.xml
add <cache-path name="my_cache_images" path="." />
:
<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
<external-path name="my_images" path="." />
+ <cache-path name="my_cache_images" path="." />
</paths>
Remove launch_splash.xml
The android/app/src/main/res/drawable/launch_splash.xml
file can be removed because it is no longer used.
Remove maven repository
Capacitor is distributed on npm, so having the maven repository entry on android/app/build.gradle
is no longer needed and can cause problems.
Remove it from repositories
section:
repositories {
- maven {
- url "https://dl.bintray.com/ionic-team/capacitor"
- }
flatDir {
dirs '../capacitor-cordova-android-plugins/src/main/libs', 'libs'
}
}