Bersiap untuk Capacitor 9: Apa yang Bisa Dilakukan Tim Aplikasi dan Plugin Sekarang

Capacitor 9 sudah tersedia di next dist-tag selagi menuju general availability. Anda tidak perlu upgrade app segera setelah versi alpha rilis, namun panduan resmi update Capacitor 9 dan panduan update plugin sudah merinci kekurangan toolchain dan penghapusan API yang perlu ditangani sejak dini.

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.

Kekurangan toolchain dan platform (apps)

Rencanakan CI, mesin lokal, dan pipeline store Anda berdasarkan standar minimum ini:

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.

Pada iOS, Swift 6 (dengan Xcode 27) menolak @UIApplicationMain; saat upgrade, ganti dengan @main di AppDelegate.swift seperti yang dijelaskan di panduan resmi.

Cordova saat sinkronisasi app (bukan langkah persiapan plugin)

Di Capacitor 9, layer kompatibilitas Cordova hanya terhubung ke app Anda saat cap sync mendeteksi adanya plugin Cordova yang terinstal. Android akan menghapus modul Gradle tambahan jika tidak ada; iOS berhenti menambahkan CapacitorCordova ke Podfile atau Package.swift jika tidak ada plugin yang terinstal.

Ini adalah app-level di level app setelah Anda upgrade. Selama masih di Cap 8, Anda tidak perlu menghapus Cordova dari template secara prematur. Audit apakah ada code native kustom (milik Anda atau plugin fork) yang mengimpor simbol Cordova tanpa adanya plugin Cordova asli di proyek — referensi tersebut akan error saat 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.gradle minimum (compile/target SDK 37, minSdkVersion 26, versi AndroidX terbaru — lihat dokumentasi resmi).
• Hapus secara eksplisit targetSdkVersion dari aplikasi build.gradle agar AGP 9 bisa menyimpulkannya dari compileSdkVersion.
• Deklarasikan variables.gradle simbol di bagian atas app/build.gradle (Gradle 9.6 mendepresiasi lookup implisit dari root project).
• Ganti nama file ProGuard default, migrasi core-ktx ke androidx.core:core 1.19.0+, hapus penggunaan standalone Kotlin Gradle plugin, dan hapus jcenter().

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 yang baru setelah upgrade.

Plugin resmi: hal penting terkait push dan splash

Dua perubahan yang berdampak pada user sering muncul di aplikasi produksi:

Push Notifications (iOS): Yang sudah usang alert yang sudah deprecated telah dihapus. Gunakan banner dan/atau list pada opsi presentation Anda.

Splash Screen (Android): Default launchFadeOutDuration berubah dari 200 ms menjadi 0. Jika Anda mengandalkan glitch fade saat first paint, atur launchFadeOutDuration: 200 secara eksplisit di capacitor.config sampai Anda menyesuaikan UI startup.

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 Capacitor plugin yang digunakan pada Capacitor 8 dan ingin code yang siap untuk Cap 9, fokuslah pada penghapusan API yang sudah deprecated, bukan pada perubahan packaging khusus Cap-9.

Aman dilakukan selama Cap 8 masih didukung:

• Ganti @NativePlugin dengan @CapacitorPlugin dan migrasikan API permission / activity-result lama ke @PermissionCallback / @ActivityCallback pola baru (lihat panduan plugin 9.0 pada tabel).
• Hapus PluginCall.hasOption, Plugin.getConfigValue, versi lama CapConfig constructor dan getter, PluginCall.save() / isSaved(), serta penghapusan Java lainnya yang tercantum di “Breaking changes in code.”
• Di iOS, berhenti menggunakan CAPBridge kelas kompatibilitas dan deprecated CAPBridgeProtocol helper yang deprecated; gunakan ApplicationDelegateProxy, typed PluginCall accessor, dan bridge properties dari tabel migrasi.
• Jalankan bunx @capacitor/plugin-migration-v8-to-v9@latest di sebuah branch dan simpan hanya edit API yang masih bisa compile terhadap peer dependencies Cap 8 sampai Anda merilis major version 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 secara eksplisit sebagai Cap 9+), setelah Anda berhenti mendukung Cap 8 — sesuai 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 versi mayor Cap 9, bukan di rilis yang kompatibel dengan Cap-8.

Capgo live updates dan native Cap 9 store build

Capgo mengirimkan update web bundle secara over the air; native shell tetap berasal dari App Store dan Google Play. Saat Anda migrasi aplikasi ke Capacitor 9:

1. Rilis minimal satu store build dikompilasi menggunakan native project Capacitor 9 (iOS dan Android). Binary tersebut menetapkan baseline native yang ditargetkan oleh Capgo channel.
2. Hanya setelah build tersebut sampai ke tangan pengguna, Anda boleh mengandalkan OTA bundle yang sudah dites terhadap perilaku WebView dan plugin Cap 9.
3. Atur production channel ke metadata strategy dan upload bundle Cap 9 yang sesuai ke setiap channel dengan --auto-min-update-version. Untuk upload native baseline yang terencana tersebut, lewati --fail-on-incompatible (native packages seharusnya berubah). Tetap --fail-on-incompatible dan --auto-min-update-version pada upload OTA harian setelahnya. Lihat Workflow channel Native + OTA.
4. Pastikan channel dan aturan semver selaras agar Anda tidak mengirim bundle yang menggunakan API Cap 9 ke perangkat yang masih menjalankan native shell versi lama.

If you use Capgo Build atau CI sendiri, refresh 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

1. 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 sebelum bunx cap migrate — perubahan proyek tersebut masuk ke tahap migrasi.
2. Perbaiki native API yang deprecated di code dan plugin (terutama custom AppDelegate penanganan URL dan penggunaan bridge Android).
3. Bersihkan Android Gradle file dan script (gradle.properties, default ProGuard, --url di dalam dev script).
4. Audit penggunaan Cordova di level aplikasi; jangan ubah produk plugin SPM Cordova sampai rilis khusus Cap 9.
5. Saat Cap 9 sudah GA (atau saat Anda menerima next), jalankan bun add -d @capacitor/cli@next (atau @latest setelah rilis), lalu bunx cap migrate, dan ikuti Update ke versi 9.0.
6. Publish native build Cap 9 ke store, lalu lanjutkan atau perluas rollout OTA Capgo pada channel yang sesuai.

Capacitor 9 fokus utamanya adalah “menyelesaikan deprecation dan menyelaraskan 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 menggunakan 8.x saat ini.