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 cek diff: dependencies Capacitor pindah ke 8.x, target Android SDK 36 dengan minSdk 24, AGP 8.13 dan Gradle 8.14.3, Kotlin naik ke 2.2.20 dengan compilerOptions, dan iOS beralih ke deployment target 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.

Apa yang berubah untuk penulis plugin

Platform tooling yang Anda butuhkan secara lokal dan di CI: Node.js 22+, Xcode 26+, Android Studio Otter (2025.2.1) atau lebih baru, 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-nya:

• Memperbarui dependensi Capacitor dan mengatur versi paket Anda menjadi 8.0.0.
• Memperbarui dev tooling yang dipakai 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.
• Membuat 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 deployment target podspec dari 14.0 ke 15.0, dan di Package.swift menetapkan .iOS(.v15) dan from: "8.0.0" untuk capacitor-swift-pm.

Saat string yang diharapkan tidak ada, ia mencatat log Unable to find "..." in <file>. Try updating it manually. Setiap baris itu adalah langkah manual untuk Anda. Plugin dengan logika Gradle kustom, folder non-standar, atau file yang diganti namanya paling banyak menghasilkan baris seperti itu.

Jika Prettier pindah dari v2 ke v3, jalankan script format dan lint setelah migrasi. Diff formatnya bisa besar, jadi commit terpisah dari perubahan fungsional.

Opsi 2: upgrade secara manual

Gunakan ini saat tool tidak bisa parse 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. Ini memungkinkan host app untuk variables.gradle mengontrol nilainya, yang menghindari error tipe “compile against version 36” di aplikasi.

Panduan = sintaks ini hanya berlaku untuk properti. Panggilan method 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'
}

Yang lain 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 layanan Google lainnya, set 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 berfungsi 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 menjadikan blok lama sebagai 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
    }
}

Pertahankan 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. Gunakan kotlin-parcelize untuk @Parcelize dan view binding untuk akses view sintetis.

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:. Aplikasi yang dibuat CapApp-SPM pin package capacitor-swift-pm ke versi persis dari @capacitor/ios aplikasi yang terpasang, dan range memungkinkan SPM me-resolve plugin Anda terhadapnya.

Plugin dengan layout proyek Xcode lama juga perlu deployment target dinaikkan di proyek 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

Yang terbuka Skill Capgo yang open mencakup capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades untuk lompatan multi-versi, dan capacitor-plugin-spm-support. Instal 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 di-log tool tersebut sebagai skipped. Tinjau diff-nya seperti Anda meninjau PR rekan tim.

Pendekatan mana yang sebaiknya digunakan

Mulai dengan tool ini dalam hampir semua kasus. Log-nya memberi tahu persis apa yang tersisa.

Verifikasi sebelum publish

1. bun install && bun run build (atau verify script Anda).
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 skemanya.
5. Instal plugin di aplikasi Capacitor 8 baru (bunx cap add ios memberikan SPM secara default) dan di aplikasi CocoaPods. Panggil setiap metode publik di perangkat fisik.
6. Jalankan bunx cap doctor di aplikasi pengujian.

Rilis

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

Capgo memelihara banyak plugin di siklus ini, dengan setiap @capgo/* major yang mengikuti major Capacitor. Anda bisa menelusurinya di direktori plugin.

Pemecahan Masalah

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

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

Namespace not specified. AGP 8+ memerlukan namespace = "..." di dalam plugin android block. 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 memakai AGP 9. Beralih 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. Anda Package.swift baris dependency ada typo atau memakai 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 versi 9. Persiapan untuk Capacitor 9 merinci perubahan yang bisa dilakukan tim plugin sekarang tanpa mengganggu pengguna Capacitor 8.