Cara Upgrade Plugin Capacitor ke Capacitor 8

Untuk upgrade plugin Capacitor ke Capacitor 8, jalankan bunx @capacitor/plugin-migration-v7-to-v8@latest dari root plugin, lalu tinjau diff: dependensi Capacitor pindah ke 8.x, target Android SDK 36 dengan minSdk 24, AGP 8.13 dan Gradle 8.14.3, Kotlin ke 2.2.20 dengan compilerOptions, dan iOS beralih ke target deployment 15.0 dengan capacitor-swift-pm 8. Terakhir, build aplikasi contoh di kedua platform dan rilis versi major baru.

Panduan ini untuk maintainer plugin. Tim aplikasi sebaiknya mengikuti Cara Upgrade Aplikasi Capacitor Anda ke Capacitor 8.

Perubahan bagi pembuat plugin

Tooling platform yang Anda butuhkan secara lokal dan di CI: Node.js 22+, Xcode 26+, Android Studio Otter (2025.2.1) atau versi terbaru, dan JDK 21.

Opsi 1: jalankan tool migrasi resmi

Dari root plugin, pada git tree yang bersih:

bunx @capacitor/plugin-migration-v7-to-v8@latest

Tool ini:

• Memperbarui dependensi Capacitor dan mengatur versi package Anda ke 8.0.0.
• Memperbarui dev tooling yang digunakan template resmi: @capacitor/docgen, Rollup, TypeScript, @types/node, dan Prettier (dari v2 ke v3 jika Anda menggunakan @ionic/prettier-config, serta prettier-plugin-java).
• Menghapus node_modules/@capacitor dan package-lock.json, lalu menjalankan npm install. Jika Anda menggunakan Bun, langkah tersebut gagal dengan peringatan. Jalankan bun install sendiri setelahnya dan commit bun.lock.
• Menghasilkan ulang Gradle wrapper dengan ./gradlew wrapper --gradle-version 8.14.3.
• Menulis ulang build.gradle: level SDK, versi AndroidX, AGP, versi Kotlin, kompatibilitas Java 21, dan kotlinOptions ke compilerOptions.
• Menaikkan podspec deployment target dari 14.0 ke 15.0, dan Package.swift mengatur .iOS(.v15) dan from: "8.0.0" untuk capacitor-swift-pm.

Jika string yang diharapkan tidak ada, ia akan mencatat log Unable to find "..." in <file>. Try updating it manually. Setiap baris tersebut merupakan langkah manual bagi Anda. Plugin dengan logika Gradle kustom, folder non-standar, atau file yang diubah namanya akan menghasilkan paling banyak log tersebut.

Jika Prettier pindah dari v2 ke v3, jalankan script format dan lint Anda setelah migrasi. Perbedaan format (diff) bisa sangat besar, jadi lakukan commit secara terpisah dari perubahan fungsional.

Opsi 2: upgrade secara manual

Gunakan ini saat tool tidak bisa memproses file Anda, atau saat Anda ingin meninjau setiap perubahan. Langkah-langkahnya mengikuti panduan resmi upgrade plugin.

1. Dependensi

{
  "devDependencies": {
    "@capacitor/android": "^8.0.0",
    "@capacitor/cli": "^8.0.0",
    "@capacitor/core": "^8.0.0",
    "@capacitor/ios": "^8.0.0"
  },
  "peerDependencies": {
    "@capacitor/core": ">=8.0.0"
  }
}

2. Level SDK Android dan sintaks Gradle

android {
    namespace = "com.example.plugin"
    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
    defaultConfig {
        minSdkVersion = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
        targetSdkVersion = project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
    }
    lintOptions {
        abortOnError = false
    }
}

Pertahankan project.hasProperty(...) ? rootProject.ext... : default pola tersebut. Ini memungkinkan host app untuk variables.gradle mengontrol nilainya, guna menghindari error tipe “compile against version 36” pada aplikasi.

Sintaks = hanya berlaku untuk properti. Method call seperti mavenCentral() tetap tidak berubah, dan maven { url = "..." } membutuhkan =.

3. Default AndroidX

Hanya naikkan versi library yang benar-benar digunakan plugin Anda. Default Capacitor 8 adalah:

ext {
    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
    androidxCoreVersion = project.hasProperty('androidxCoreVersion') ? rootProject.ext.androidxCoreVersion : '1.17.0'
    androidxActivityVersion = project.hasProperty('androidxActivityVersion') ? rootProject.ext.androidxActivityVersion : '1.11.0'
    androidxWebkitVersion = project.hasProperty('androidxWebkitVersion') ? rootProject.ext.androidxWebkitVersion : '1.14.0'
}

Lainnya dari daftar resmi: androidxCoordinatorLayoutVersion 1.3.0, androidxFragmentVersion 1.8.9, firebaseMessagingVersion 25.0.1, androidxBrowserVersion 1.9.0, androidxMaterialVersion 1.13.0, androidxExifInterfaceVersion 1.4.1, coreSplashScreenVersion 1.2.0.

4. AGP dan Gradle wrapper

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
    }
}

cd android
./gradlew wrapper --distribution-type all --gradle-version 8.14.3

Jika plugin Anda menggunakan Firebase atau Google Services lainnya, atur com.google.gms:google-services ke 4.4.4.

5. Java 21 dan Kotlin 2.2

Java 21 direkomendasikan untuk AGP 8.13 dan SDK 36. Java 17 masih bisa digunakan untuk plugin itu sendiri.

compileOptions {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
}

Untuk plugin Kotlin, perbarui versi default dan pindahkan jvmTarget keluar dari kotlinOptions. Kotlin 2.2 membuat blok lama menjadi error:

import org.jetbrains.kotlin.gradle.dsl.JvmTarget

buildscript {
    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
}

android {
    // remove: kotlinOptions { jvmTarget = '17' }
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.JVM_21
    }
}

Tetap jvmTarget dan targetCompatibility pada versi Java yang sama, atau Gradle akan berhenti dengan error “Inconsistent JVM-target compatibility”. Jika Anda masih menerapkan kotlin-android-extensions, hapus saja. Gunakan kotlin-parcelize untuk @Parcelize dan view binding untuk akses synthetic view.

6. Target deployment iOS

Podspec:

s.ios.deployment_target = '15.0'

Package.swift:

platforms: [.iOS(.v15)],
dependencies: [
    .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
],

Gunakan from:, bukan branch: atau exact:. App yang di-generate CapApp-SPM pin paket capacitor-swift-pm ke versi eksak dari @capacitor/ios app yang terinstal, dan range memungkinkan SPM melakukan resolve plugin terhadapnya.

Plugin dengan tata letak proyek Xcode lama juga perlu menaikkan deployment target di dalam proyeknya Pengaturan Build dan di ios/Podfile (platform :ios, '15.0').

Jika plugin Anda tidak memiliki Package.swift belum, lakukan itu selanjutnya. Aplikasi yang dibuat dengan Capacitor 8 secara default menggunakan SPM dan akan melewati plugin Anda dengan peringatan “not compatible with SPM”. Ikuti Cara Migrasi Plugin Capacitor ke Swift Package Manager.

Opsi 3: biarkan agent melakukannya

Terbuka Keahlian Capgo mencakup capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades untuk lompatan multi-versi, dan capacitor-plugin-spm-support. Install dengan bunx skills add Cap-go/capgo-skills dan minta agent Anda untuk upgrade plugin tersebut. Skill ini menjalankan tool resmi, lalu menangani langkah-langkah yang tercatat sebagai skipped oleh tool tersebut. Review diff-nya sama seperti Anda mereview PR rekan tim.

Pendekatan mana yang digunakan

Gunakan tool ini hampir di setiap kasus. Log-nya akan memberi tahu apa yang perlu dilakukan.

Verifikasi sebelum publish

1. bun install && bun run build (or your verify script).
2. Android: cd android && ./gradlew clean build test. Build dengan JDK 21.
3. iOS dengan CocoaPods: cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS (plugin layout baru menggunakan xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
4. iOS dengan SPM: swift package resolve, lalu build schemenya.
5. Install plugin di app Capacitor 8 baru (bunx cap add ios memberikan SPM secara default) dan pada aplikasi CocoaPods. Panggil setiap method publik di perangkat asli.
6. Jalankan bunx cap doctor di aplikasi pengujian.

Rilis

• Naikkan ke versi major baru (tool ini menggunakan 8.0.0). Menaikkan minSdk dan batas minimum iOS adalah breaking change bagi pengguna.
• Tulis teks singkat BREAKING.md atau entri changelog singkat: peer range baru, minSdk 24, iOS 15, Java 21 untuk build, serta perubahan perilaku API apa pun.
• Pertahankan 7.x branch jika Anda masih mengirimkan perbaikan untuk pengguna Capacitor 7, dan publikasikan di bawah dist-tag seperti latest-7.
• Perbarui bagian instalasi README dan tabel kompatibilitas.

Capgo mengelola banyak plugin pada siklus ini, dengan masing-masing @capgo/* perubahan besar pada Capacitor major. Anda dapat mencarinya di direktori plugin.

Troubleshooting

invalid source release: 21. Gradle berjalan pada JDK 17 atau versi lama. Gunakan JDK 21 bawaan Android Studio Otter dan atur JAVA_HOME di CI.

Unsupported class file major version 65. Masalah sebaliknya: Anda menjalankan JDK 21 dengan Gradle wrapper lama yang tidak bisa membaca file class Java 21. Regenerate wrapper ke 8.14.3.

Namespace not specified. AGP 8+ memerlukan namespace = "..." di dalam plugin tersebut android plugin. Plugin lama hanya memiliki package attribute di AndroidManifest.xml. Pindahkan ke Gradle dan hapus package dari manifest.

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). Kotlin Anda jvmTarget tidak cocok targetCompatibility. Atur keduanya ke 21 atau keduanya ke 17.

Error yang menyebutkan proguard-android.txt dengan AGP 9. Beberapa aplikasi sudah menjalankan AGP 9. Beralihlah ke proguard-android-optimize.txt agar plugin Anda juga bisa di-build di aplikasi tersebut. Detailnya ada di cara memperbaiki error build plugin Capacitor dengan AGP 9.

SPM: product 'Capacitor' required by package ... not found. Dependency Package.swift Anda memiliki typo atau menggunakan versi yang tidak ada. Gunakan from: "8.0.0" terhadap https://github.com/ionic-team/capacitor-swift-pm.git.

Peringatan page size 16 KB di Play Console. Jika plugin Anda menyertakan native .so library, build ulang dengan alignment 16 KB. Lihat Android 16 KB page size dan plugin Capacitor.

Setelah plugin di versi 8, langkah berikutnya adalah bersiap untuk 9. Persiapan untuk Capacitor 9 berisi daftar perubahan yang bisa dilakukan tim plugin sekarang tanpa mengganggu pengguna Capacitor 8.