Cara Upgrade Aplikasi Capacitor Anda ke Capacitor 8

Untuk upgrade aplikasi Capacitor ke Capacitor 8, instal Node.js 22+, Xcode 26+ dan Android Studio Otter, update @capacitor/cli ke versi 8.x terbaru, jalankan bunx cap migrate, lalu perbaiki apa pun yang dilaporkan oleh migrator. Breaking changes utamanya adalah iOS 15 sebagai target deployment minimum, Android SDK 36 dengan minSdk 24, AGP 8.13 dengan Gradle 8.14.3, serta penghapusan adjustMarginsForEdgeToEdge yang digantikan oleh plugin System Bars yang baru.

Panduan ini membahas jalur otomatis, setiap langkah manual di baliknya, dan error yang paling sering muncul setelah upgrade. Jika Anda memelihara plugin, bukan aplikasi, baca Cara Upgrade Plugin Capacitor Anda ke Capacitor 8 instead.

Ringkasan persyaratan Capacitor 8

Periksa toolchain Anda sebelum menyentuh proyek. Kebanyakan upgrade yang gagal disebabkan oleh JDK lama, Xcode lama, atau Node lama di CI, bukan karena code.

Xcode 26 bukan sekadar syarat Capacitor. Sejak 28 April 2026, App Store Connect menolak upload yang dibuat dengan Xcode lama, jadi Anda tetap membutuhkannya. Lihat Persyaratan Xcode 26 dari Apple untuk app Capacitor untuk detailnya.

Sebelum memulai

1. Commit semua perubahan, atau buat branch baru. Migrator akan mengedit file native secara langsung.
2. Pastikan app Anda bisa build di Capacitor 7 sekarang. Upgrade project yang sedang error hanya akan menambah masalah.
3. Jika Anda menggunakan Capacitor 6 atau versi lama, lakukan migrasi major sebelumnya dulu. Setiap versi major punya logika migrasi sendiri di CLI.
4. List plugin Anda dengan bunx cap ls dan pastikan tiap plugin punya rilis yang mendukung Capacitor 8. Cek di peerDependencies dari versi terbaru:

bun pm view @capgo/capacitor-updater peerDependencies

Plugin dengan @capacitor/core: ^7.0.0 karena peer-nya akan terinstal dengan peringatan dan mungkin gagal saat kompilasi. Plugin Capgo mengikuti Capacitor major pada nomor versi mereka sendiri, jadi @capgo/* rilis 8.x menargetkan Capacitor 8.

5. Update toolchain lokal dan CI: Node 22, Xcode 26, JDK 21, Android Studio Otter. Di GitHub Actions, gunakan macOS image yang menyertakan Xcode 26 dan gunakan actions/setup-java dengan java-version: '21'.

Opsi 1: upgrade dengan cap migrate

CLI menyertakan perintah migrasi yang menangani sebagian besar prosesnya. Instal CLI terbaru, lalu jalankan perintah ini:

bun add -D @capacitor/cli@latest
bunx cap migrate

Migrator akan bertanya apakah perlu menginstal paket Capacitor baru dan membiarkan Anda memilih npm, Yarn, pnpm, atau Bun. Pilih Bun jika proyek Anda memiliki bun.lock. Anda bisa melewati prompt dengan bunx cap migrate --noprompt.

Apa yang berubah untuk Anda:

• Menaikkan @capacitor/core, @capacitor/ios, @capacitor/android dan plugin resmi @capacitor/* ke versi 8.x.
• Mengatur IPHONEOS_DEPLOYMENT_TARGET = 15.0 di proyek Xcode dan platform :ios, '15.0' di Podfile.
• Update variables.gradle, AGP classpath, Gradle wrapper, dan kotlin_version.
• Menambahkan density ke android:configChanges di AndroidManifest.xml.

Baca output selengkapnya. Jika suatu langkah tidak bisa diterapkan, misalnya karena file telah dikustomisasi, CLI akan mencetak error beserta nama filenya dan lanjut ke tahap berikutnya. Baris-baris tersebut adalah daftar tugas manual Anda.

Setelah selesai:

bun run build
bunx cap sync

Kemudian buka setiap platform dan lakukan build sekali dari IDE agar Anda bisa melihat error native secara lengkap.

Opsi 2: upgrade secara manual

Jika proyek native Anda banyak kustomisasi, atau migrator melewatkan beberapa langkah, terapkan perubahan secara manual. Ini sesuai dengan panduan upgrade resmi Capacitor 8.

Perbarui paket npm

bun add @capacitor/core@latest @capacitor/ios@latest @capacitor/android@latest
bun add -D @capacitor/cli@latest

Kemudian update setiap plugin resmi, contohnya:

bun add @capacitor/app@latest @capacitor/splash-screen@latest @capacitor/status-bar@latest

iOS: naikkan deployment target ke 15.0

Di Xcode, pilih project, buka Pengaturan Build, cari Target Deployment iOS di bawah Deployment dan atur ke 15.0. Ulangi untuk setiap target app, termasuk extension.

Jika app masih menggunakan CocoaPods, update ios/App/Podfile:

platform :ios, '15.0'

Lalu jalankan bunx cap sync ios, yang menjalankan pod install untuk Anda.

Jika app menggunakan SPM, CLI akan regenerasi ios/App/CapApp-SPM/Package.swift setiap kali sync dengan versi platform yang tepat dan capacitor-swift-pm versi yang sesuai dengan yang terinstal di @capacitor/ios. Jangan edit file tersebut secara manual.

iOS: hapus custom view controller notifications

Capacitor 8 sekarang mengeluarkan CAPBridgeViewController notifikasi untuk viewDidAppear dan viewWillTransition itu sendiri. Jika Anda menambahkan ekstensi atau subclass untuk mengirim .capacitorViewDidAppear atau .capacitorViewWillTransition, hapuslah, atau listener akan terpanggil dua kali.

Android: perbarui Android Studio dan AGP

Instal Android Studio Otter atau yang lebih baru, buka android folder dan jalankan Tools > AGP Upgrade Assistant. Pilih 8.13.0 dan jalankan langkah-langkah yang dipilih. Atau edit android/build.gradle secara langsung:

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
        classpath 'com.google.gms:google-services:4.4.4'
    }
}

Dan android/gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip

Android: perbarui variables.gradle

ext {
    minSdkVersion = 24
    compileSdkVersion = 36
    targetSdkVersion = 36
    androidxActivityVersion = '1.11.0'
    androidxAppCompatVersion = '1.7.1'
    androidxCoordinatorLayoutVersion = '1.3.0'
    androidxCoreVersion = '1.17.0'
    androidxFragmentVersion = '1.8.9'
    coreSplashScreenVersion = '1.2.0'
    androidxWebkitVersion = '1.14.0'
    junitVersion = '4.13.2'
    androidxJunitVersion = '1.3.0'
    androidxEspressoCoreVersion = '3.7.0'
    cordovaAndroidVersion = '14.0.1'
}

Pertahankan variabel tambahan yang dibaca plugin Anda (misalnya firebaseMessagingVersion). Update plugin resmi untuk Capacitor 8 mencakup firebaseMessagingVersion = '25.0.1', androidxBrowserVersion = '1.9.0', androidxMaterialVersion = '1.13.0' dan androidxExifInterfaceVersion = '1.4.1'.

Android: beralih ke = assignment di file Gradle

Gradle telah mendepresiasi sintaks space-assignment. Saat ini baru berupa peringatan, namun akan error pada rilis Gradle mendatang, jadi segera perbaiki di android/app/build.gradle:

android {
-    namespace "com.example.app"
-    compileSdk rootProject.ext.compileSdkVersion
+    namespace = "com.example.app"
+    compileSdk = rootProject.ext.compileSdkVersion
     defaultConfig {
         aaptOptions {
-            ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
+            ignoreAssetsPattern = '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
         }
     }
}

Pemanggilan method seperti google() atau mavenCentral() tetap seperti semula.

Android: Kotlin dan configChanges

Jika modul aplikasi Anda menggunakan Kotlin, atur kotlin_version = '2.2.20'. Kotlin 2.x mengubah yang lama menjadi kotlinOptions {} error, jadi pindahkan jvmTarget ke dalam kotlin { compilerOptions { ... } }.

Lalu tambahkan density ke main activity agar WebView tidak dibuat ulang saat densitas layar berubah (foldables, resize window, pengaturan ukuran layar):

android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"

Android: layout bridge telah diubah namanya

bridge_layout_main.xml tidak ada lagi. Jika MainActivity atau fragment kustom yang merujuk pada R.layout.bridge_layout_main, gunakan R.layout.capacitor_bridge_layout_main.

Edge-to-edge dan plugin System Bars baru

Ini adalah perubahan yang paling terlihat secara visual. Capacitor 8 menghapus android.adjustMarginsForEdgeToEdge dan menambahkan plugin core System Bars. Anda tidak perlu menginstalnya, sudah termasuk dalam @capacitor/core.

Android 15 mewajibkan tampilan edge-to-edge untuk aplikasi dengan target SDK 35, dan Android 16 menghapus opsi opt-out untuk target SDK 36. Capacitor 8 menargetkan 36, jadi konten web Anda sekarang akan tampil di belakang status dan navigation bar kecuali Anda menangani insets.

Konfigurasi plugin berada di bawah plugins.SystemBars:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    SystemBars: {
      // 'css' (default) injects --safe-area-inset-* variables on Android
      // 'native' relies on env() and viewport-fit
      // 'disable' leaves inset handling entirely to you
      insetsHandling: 'css',
      initialViewportFitValueHint: 'cover',
    },
  },
};

export default config;

Dengan css atau native, Android WebView yang lebih baru (Chromium 140+) mengikuti viewport-fit=cover dan melaporkan nilai env(safe-area-inset-*) asli. Pada WebView lama, Capacitor memberi padding pada WebView dan mengatur nilai env ke 0px. Jadi, pasang meta tag dan gunakan variabel berikut:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
}

Saat runtime, Anda dapat mengubah gaya atau visibilitas bar:

import { SystemBars, SystemBarsStyle, SystemBarType } from '@capacitor/core';

await SystemBars.setStyle({ style: SystemBarsStyle.Dark });
await SystemBars.hide({ bar: SystemBarType.NavigationBar });

Aplikasi Ionic Framework sudah menggunakan variabel safe-area, jadi biasanya hanya butuh meta tag. Artikel lama kami tentang edge-to-edge tanpa plugin menjelaskan opsi Capacitor 7, yang sudah tidak ada lagi di versi 8.

Perubahan perilaku lainnya yang perlu dicek

• appendUserAgent di iOS: Capacitor 7 menambahkan dua spasi sebelum string Anda, Capacitor 8 menambahkan satu. Jika server Anda memparsing user agent secara ketat, tambahkan spasi di depan ios.appendUserAgent (bukan pada opsi root, yang juga berdampak pada Android).
• Screen Orientation dan Barcode Scanner: pada layar besar Android 16+, penguncian orientasi akan diabaikan. Opsi opt-out sementara tersedia melalui android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY properti manifest, namun Android 17 akan menghapusnya.
• Geolocation: timeout sekarang berlaku untuk semua request di Android dan iOS. Jika muncul timeout baru, naikkan nilainya. watchPosition pada Android mendapatkan interval opsi.
• Status Bar: plugin tidak lagi menyertakan CAPBridgeViewController file notifikasi, karena core sekarang memancarkan event tersebut.
• Platform iOS baru secara default menggunakan SPM: bunx cap add ios sekarang membuat proyek SPM. Gunakan --packagemanager CocoaPods jika Anda butuh template lama. Lihat cara menggunakan CocoaPods dengan Capacitor 8.

Verifikasi upgrade

Cek daftar ini di kedua platform sebelum Anda rilis:

bunx cap doctor
bunx cap sync
bunx cap run ios
bunx cap run android

• cap doctor menampilkan versi 8.x yang cocok untuk core, CLI, iOS, dan Android.
• App launch, splash screen hilang, deep link membuka layar yang benar.
• Area status bar dan navigation bar terlihat benar di perangkat Android 15/16 dan iPhone dengan notch.
• Push notification, kamera, akses file, dan plugin dengan native permission tetap berfungsi.
• Build rilis (Archive di Xcode, ./gradlew bundleRelease) berhasil, bukan cuma debug.

Jika Anda tidak ingin mengelola Xcode 26 dan JDK 21 di setiap mesin, Capgo Build menjalankan build iOS dan Android di cloud dengan toolchain terbaru.

Rilis upgrade dengan aman menggunakan Live Update

Upgrade major Capacitor mengubah native code, jadi harus melalui App Store dan Google Play. Web bundle yang dibuat setelah upgrade mungkin memanggil plugin API yang tidak ada di binary lama.

If you use Live updates Capgo, pisahkan Capacitor 7 user dan Capacitor 8 user sampai adopsi merata: naikkan versi native, upload bundle baru ke channel yang digunakan binary baru, dan jalankan pengecekan kompatibilitas sebelum Anda upload:

bunx @capgo/cli@latest bundle compatibility

Ini membandingkan versi plugin native di bundle Anda dengan yang berjalan di channel dan menandai ketidakcocokan sebelum user menerima update yang error.

Troubleshooting error umum upgrade Capacitor 8

The engine "node" is incompatible atau CLI menolak untuk berjalan. Anda menggunakan Node 20 atau versi lama. Install Node 22 LTS, dan update juga image CI Anda.

error: invalid source release: 21 di Android. Gradle berjalan dengan JDK 17. Arahkan Android Studio ke bundled JDK 21 (Pengaturan > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK) dan atur JAVA_HOME ke JDK 21 untuk build command-line dan CI.

Minimum supported Gradle version is 8.13. Anda sudah update AGP tapi belum wrapper-nya. Set wrapper ke 8.14.3.

Dependency ... requires libraries and applications that depend on it to compile against version 36. compileSdkVersion masih 35 di suatu tempat. Cek variables.gradle and any plugin that hardcodes it.

Using 'kotlinOptions' ... is an error atau error Kotlin DSL serupa. Plugin atau modul app Anda masih menggunakan kotlinOptions. Update plugin tersebut, atau patch sampai rilis tersedia (lihat cara patch plugin Capacitor).

Xcode: No such module 'Capacitor' setelah upgrade. Untuk CocoaPods, buka App.xcworkspace, bukan App.xcodeproj, and rerun bunx cap sync ios. Untuk SPM, gunakan File > Packages > Reset Package Caches.

"X" plugin is not implemented on ios/android. Plugin tidak tersinkron, atau tidak punya rilis Capacitor 8 / SPM-compatible. Jalankan bunx cap sync dan baca peringatannya.

Untuk daftar yang lebih lengkap, lihat Panduan troubleshooting Capacitor iOS dan Panduan troubleshooting Android. Ketidakcocokan versi core dan plugin dibahas di Cara memperbaiki error mismatch versi Capacitor.

Biarkan AI agent menangani bagian yang membosankan

Jika Anda menggunakan Claude Code, Cursor, atau agent serupa, fitur Skill Capgo yang open mencakup capacitor-app-upgrade-v7-to-v8 dan capacitor-app-upgrades untuk lompatan multi-major. Instal dengan bunx skills add Cap-go/capgo-skills dan minta agent untuk meng-upgrade aplikasi. Agent menjalankan migrator, lalu memeriksa langkah-langkah yang biasanya terlewat oleh CLI, seperti sintaks Gradle, opsi Kotlin, dan image CI.

Apa langkah selanjutnya

Capacitor 9 sudah tersedia dalam versi prerelease. Setelah Anda stabil di versi 8, baca Persiapan untuk Capacitor 9 agar upgrade berikutnya lebih ringan.