Capacitor 9 sudah tersedia di next dist-tag selagi menuju general availability. Anda tidak wajib upgrade app saat versi alpha rilis, tapi panduan resmi update Capacitor 9 dan panduan update plugin sudah merinci perubahan toolchain dan penghapusan API yang perlu ditangani sejak awal.
Artikel ini adalah persiapan checklist: hal yang bisa Anda kerjakan di Capacitor 8 (atau di branch) agar proses bunx cap migrate migrasi nantinya berjalan lancar tanpa kendala. Saat siap untuk migrasi, ikuti panduan Ionic di atas baris demi baris.
Toolchain dan versi minimum platform (apps)
Rencanakan CI, mesin lokal, dan pipeline store Anda berdasarkan persyaratan minimum ini:
| Aspek | persyaratan Capacitor 9 |
|---|---|
| Node.js | 24+ (disarankan versi LTS terbaru; npm 11 menyertakan Node 24) |
| Xcode | 27+ |
| target deployment iOS | 16.0+ |
| Android Studio | 2026.1.1+ |
| Android Gradle Plugin (AGP) | 9.2.1 |
| Gradle wrapper | 9.5.1 |
Jika Anda masih menggunakan Capacitor 8.4 atau versi sebelumnya untuk iOS, Anda juga butuh lifecycle UIScene dari update Capacitor 8.5 sebelum Cap 9 — Xcode 27 membutuhkannya. Aplikasi yang sudah di versi 8.5 bisa melewati langkah ini.
Di iOS, Swift 6 (dengan Xcode 27) menolak @UIApplicationMain; saat upgrade, ganti dengan @main di AppDelegate.swift seperti yang dijelaskan di panduan resmi.
Cordova saat sync app (bukan langkah persiapan plugin)
Di Capacitor 9, layer kompatibilitas Cordova hanya disambungkan ke aplikasi Anda saat cap sync mendeteksi plugin Cordova yang terinstal. Android menghapus modul Gradle tambahan jika tidak ada; iOS berhenti menambahkan CapacitorCordova ke Podfile atau Package.swift ketika tidak ada yang tersedia.
Itu adalah app-level di level aplikasi setelah Anda upgrade. Selama masih di Cap 8, Anda tidak perlu mencabut Cordova dari template secara prematur. Periksa apakah ada code native kustom (milik Anda atau plugin hasil fork) mengimpor simbol Cordova tanpa plugin Cordova yang benar-benar ada di proyek — referensi tersebut akan gagal begitu wiring Cordova opsional diterapkan.
Android: gradle.properties dan default AGP 9
AGP Upgrade Assistant sering menulis flag eksplisit gradle.properties agar build tetap menggunakan perilaku AGP 8. Aplikasi Capacitor 9 harus menghapus entri tersebut alih-alih membawanya ke versi berikutnya: sebagian besar sudah deprecated menjelang AGP 10, dan beberapa merusak build Cap 9 (contohnya android.builtInKotlin=false menonaktifkan dukungan Kotlin yang dibundel AGP 9, dan android.sdk.defaultTargetSdkToCompileSdkIfUnset=false membuat AGP berhenti menginferensi targetSdkVersion).
Saat migrasi, Anda juga perlu:
- Naikkan
variables.gradleminimum (compile/target SDK 37,minSdkVersion26, versi AndroidX terbaru — lihat dokumentasi resmi). - Hapus secara eksplisit
targetSdkVersiondari aplikasibuild.gradleagar AGP 9 bisa menyimpulkannya daricompileSdkVersion. - Deklarasikan
variables.gradlesimbol di bagian atasapp/build.gradle(Gradle 9.6 mendepresiasi lookup implisit dari root project). - Ganti nama file ProGuard default, migrasi
core-ktxkeandroidx.core:core1.19.0+, hapus penggunaan standalone Kotlin Gradle plugin, dan hapusjcenter().
Anda bisa membaca diff hunk di Update ke 9.0 bagian Android dan terapkan pembersihan yang sama di branch sebelum menaikkan versi Capacitor.
CLI: cap run --url
Capacitor 9 menggabungkan flag live-reload host/port/https menjadi satu --url argumen. Alih-alih:
bunx cap run android -l --host 192.168.1.181 --port 5173
masukkan URL yang muncul di dev server Anda:
bunx cap run android --url http://192.168.1.181:5173/
Perbarui script dan cuplikan README sekarang agar muscle memory Anda tidak terganggu oleh CLI baru setelah upgrade.
Plugin resmi: hal penting terkait push dan splash
Dua perubahan pada sisi user sering muncul di aplikasi produksi:
Push Notifications (iOS): Yang sudah tidak digunakan lagi alert yang sudah deprecated telah dihapus. Gunakan banner dan/atau list pada opsi presentation Anda.
Splash Screen (Android): Default launchFadeOutDuration berubah dari 200 ms ke 0. Jika Anda mengandalkan glitch fade saat menyembunyikan first paint, atur launchFadeOutDuration: 200 secara eksplisit di capacitor.config sampai Anda menyesuaikan UI startup Anda.
Pindai bagian plugin di dalam panduan update 9.0 untuk kenaikan versi AndroidX dan Google Play Services pada plugin resmi yang Anda gunakan.
Maintainer plugin: bersiaplah di Cap 8 tanpa merusak Cap 8
Jika Anda merilis plugin Capacitor yang digunakan pada Capacitor 8 dan ingin code yang siap Cap 9, fokuslah pada penghapusan API yang deprecated, bukan pada perubahan packaging khusus Cap-9.
Aman dilakukan selama Cap 8 masih didukung:
- Ganti
@NativePlugindengan@CapacitorPlugindan migrasi API permission / activity-result lama ke@PermissionCallback/@ActivityCallbackpola baru (lihat panduan plugin 9.0 pada tabel). - Hapus
PluginCall.hasOption,Plugin.getConfigValue, lamaCapConfigconstructor dan getter,PluginCall.save()/isSaved(), serta penghapusan Java lain yang tercantum di “Breaking changes di code.” - Di iOS, berhenti menggunakan
CAPBridgeclass kompatibilitas dan deprecatedCAPBridgeProtocolhelper yang deprecated; gunakanApplicationDelegateProxy, bertipePluginCall, dan bridge properties dari tabel migrasi. - Jalankan
bunx @capacitor/plugin-migration-v8-to-v9@latestdi sebuah branch dan simpan hanya edit API yang masih bisa compile terhadap peer dependencies Cap 8 sampai Anda merilis versi major untuk Cap 9.
Jangan hapus Cordova produk SPM dari plugin Anda Package.swift selama Anda masih mendukung Capacitor 8. Proyek Cap 8 mengharapkan dependensi tersebut jika plugin Anda berbasis SPM; menghentikannya terlalu dini akan merusak pengguna yang masih di versi 8. Perlakukan opsional Cordova / menghapus yang tanpa syarat Cordova produk sebagai Capacitor khusus versi 9 jalur rilis (atau semver major yang didokumentasikan eksplisit sebagai Cap 9+), setelah Anda berhenti mendukung Cap 8 — seperti yang dijelaskan dalam panduan plugin, bukan sebagai persiapan di jalur Cap 8.
Aturan praktis yang sama berlaku untuk menaikkan versi capacitor-swift-pm ke 9.0.0-alpha.x di Package.swift: itu seharusnya ada di major Cap 9 Anda, bukan pada rilis yang kompatibel dengan Cap 8.
Capgo live updates dan native Cap 9 store build
Capgo mengirimkan web bundle update secara over the air; native shell tetap berasal dari App Store dan Google Play. Saat Anda memindahkan aplikasi ke Capacitor 9:
- Rilis setidaknya satu store build dikompilasi terhadap project native Capacitor 9 (iOS dan Android). Binary tersebut menetapkan baseline native yang ditargetkan channel Capgo.
- Hanya setelah build tersebut sampai ke tangan pengguna, Anda boleh mengandalkan OTA bundle yang sudah dites terhadap perilaku WebView dan plugin Cap 9.
- Atur channel production ke
metadatastrategy dan upload bundle Cap 9 yang sesuai ke setiap channel dengan--auto-min-update-version. Untuk upload baseline native yang disengaja itu, lewati--fail-on-incompatible(native packages seharusnya berubah). Pertahankan--fail-on-incompatibledan--auto-min-update-versionpada upload OTA harian setelahnya. Lihat Alur kerja channel Native + OTA. - Selaraskan channel dan aturan semver agar Anda tidak mengirim bundle yang menggunakan API Cap 9 ke perangkat yang masih menggunakan native shell versi lama.
If you use Build Capgo atau CI sendiri, perbarui agent sebelum rilis store Cap 9 agar pipeline sesuai dengan yang diinstal pengguna: macOS runner membutuhkan Node 24+ dan Xcode 27+; Linux runner butuh Node 24+ dan Android tooling yang sesuai dengan AGP 9.2.1 / Gradle 9.5.1 (Xcode hanya untuk macOS).
Urutan langkah yang disarankan
- Upgrade tooling yang terinstal pada host CI dan mesin developer ke versi di atas (Node, Xcode, Android Studio, JDK). Jangan update dependency AGP, Gradle wrapper, atau file proyek Android lainnya dari Cap 8 ke Cap 9 sampai
bunx cap migrate— perubahan proyek tersebut masuk ke tahap migrasi. - Perbaiki native API yang deprecated di code app dan plugin (terutama custom
AppDelegatepenanganan URL dan penggunaan bridge Android). - Bersihkan Android Gradle file dan script (
gradle.properties, default ProGuard,--urldi dalam dev script). - Audit penggunaan Cordova di level aplikasi; jangan ubah produk plugin SPM Cordova sampai rilis khusus Cap 9.
- Saat Cap 9 sudah GA (atau saat Anda menerima
next), jalankanbun add -d @capacitor/cli@next(atau@latestsetelah rilis), lalubunx cap migrate, dan ikuti Update ke 9.0. - Publish native build Cap 9 ke store, lalu lanjutkan atau perluas rollout OTA Capgo pada channel yang sesuai.
Capacitor 9 sebagian besar berisi “penghapusan deprecations dan penyelarasan dengan toolchain Android serta Apple modern.” Melakukan hal tersebut di Cap 8 akan menjaga diff upgrade tetap kecil dan plugin Anda tetap kompatibel dengan tim yang masih merilis 8.x saat ini.