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 hanya persyaratan Capacitor. Sejak 28 April 2026, App Store Connect menolak upload yang dibangun dengan Xcode versi lama, jadi Anda membutuhkannya anyway. Lihat Persyaratan Xcode 26 dari Apple untuk app Capacitor untuk detailnya.

Sebelum memulai

1. Commit semua perubahan, atau buat branch. Migrator akan mengedit file native secara langsung.
2. Pastikan app bisa di-build di Capacitor 7 saat ini. Upgrade proyek yang rusak hanya akan menambah masalah.
3. Jika Anda masih di Capacitor 6 atau lebih lama, lakukan upgrade major sebelumnya dulu. Setiap major memiliki logika migrasi sendiri di CLI.
4. Daftarkan plugin Anda dengan bunx cap ls dan pastikan setiap plugin memiliki release yang mendukung Capacitor 8. Lihat peerDependencies dari versi terbaru:

bun pm view @capgo/capacitor-updater peerDependencies

Plugin dengan @capacitor/core: ^7.0.0 sebagai peer akan terinstall dengan peringatan dan mungkin gagal di-compile. Plugin Capgo mengikuti major Capacitor dalam nomor versi mereka, jadi @capgo/* release 8.x menargetkan Capacitor 8.

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

Opsi 1: upgrade dengan cap migrate

CLI menyediakan perintah migrasi yang menangani sebagian besar pekerjaan. Instal CLI terbaru, lalu jalankan:

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

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

Apa yang berubah untuk Anda:

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

Baca output lengkapnya. Jika ada langkah yang tidak bisa diterapkan, misalnya karena file sudah dikustomisasi, CLI akan mencetak error dengan nama file dan melanjutkan. Baris-baris itu adalah daftar to-do manual Anda.

Setelah selesai:

bun run build
bunx cap sync

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

Opsi 2: upgrade secara manual

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

Perbarui paket npm

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

Lalu perbarui setiap plugin resmi, misalnya:

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

iOS: naikkan deployment target ke 15.0

Di Xcode, pilih proyek, buka Pengaturan Build, cari Target Deployment iOS di bawah Deployment dan atur ke 15.0. Ulangi untuk setiap target aplikasi, termasuk ekstensi.

Jika aplikasi masih menggunakan CocoaPods, perbarui ios/App/Podfile:

platform :ios, '15.0'

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

Jika aplikasi menggunakan SPM, CLI akan membuat ulang ios/App/CapApp-SPM/Package.swift pada setiap sync dengan versi platform yang tepat dan capacitor-swift-pm versi yang cocok dengan yang terinstal @capacitor/ios. Jangan edit file tersebut secara manual.

iOS: hapus notifikasi custom view controller

Capacitor 8 sekarang mengirimkan CAPBridgeViewController notifikasi untuk viewDidAppear dan viewWillTransition dirinya sendiri. Jika Anda menambahkan extension atau subclass untuk mengirim .capacitorViewDidAppear atau .capacitorViewWillTransition, hapus saja, atau listener akan terpicu dua kali.

Android: update 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 yang dipilih. Atau edit android/build.gradle 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). Peningkatan versi 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 = penugasan dalam file Gradle

Gradle telah men-deprecate sintaks penugasan dengan spasi. Saat ini hanya memberikan peringatan, tetapi akan rusak pada rilis Gradle mendatang, jadi perbaiki sekarang 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 app Anda menggunakan Kotlin, atur kotlin_version = '2.2.20'. Kotlin 2.x mengubah kotlinOptions {} block lama menjadi error, jadi pindahkan jvmTarget ke dalam kotlin { compilerOptions { ... } }.

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

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

Android: layout bridge diganti namanya

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

Edge-to-edge dan plugin System Bars baru

Ini perubahan yang paling mungkin terlihat secara visual. Capacitor 8 menghapus android.adjustMarginsForEdgeToEdge dan menambahkan plugin System Bars inti. Anda tidak perlu menginstalnya, plugin ini sudah disertakan dengan @capacitor/core.

Android 15 memaksa edge-to-edge untuk aplikasi yang menargetkan SDK 35, dan Android 16 menghapus opsi opt-out untuk aplikasi yang menargetkan SDK 36. Capacitor 8 menargetkan 36, sehingga konten web Anda sekarang dirender di belakang status bar 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 WebViews yang lebih baru (Chromium 140+) mendukung viewport-fit=cover dan melaporkan nilai env(safe-area-inset-*) yang sebenarnya. Pada WebView lama, Capacitor memberi padding pada WebView dan mengatur nilai env menjadi 0px. Jadi, setel 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 bisa 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 perlu meta tag. Artikel lama kami tentang edge-to-edge tanpa plugin menjelaskan opsi Capacitor 7, yang tidak lagi ada di versi 8.

Perubahan perilaku lain yang perlu diperiksa

• appendUserAgent di iOS: Capacitor 7 menambahkan dua spasi sebelum string Anda, Capacitor 8 menambahkan satu. Jika server Anda mem-parsing user agent secara ketat, tambahkan spasi di awal ios.appendUserAgent (bukan opsi root, yang juga memengaruhi Android).
• Orientasi Layar dan Barcode Scanner: di Android 16+ dengan layar besar, penguncian orientasi diabaikan. Ada opt-out sementara melalui android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY properti manifest, tetapi Android 17 menghapusnya.
• Geolokasi: timeout sekarang berlaku untuk semua permintaan di Android dan iOS. Jika Anda melihat timeout baru, tingkatkan nilainya. watchPosition di 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 membutuhkan template lama. Lihat cara menggunakan CocoaPods dengan Capacitor 8.

Verifikasi upgrade

Lakukan daftar ini di kedua platform sebelum 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.
• Aplikasi terbuka, splash screen tersembunyi, dan deep link membuka layar yang benar.
• Area status bar dan navigation bar terlihat benar di perangkat Android 15/16 dan iPhone berponi.
• Push notification, kamera, akses file, dan plugin apa pun dengan izin native tetap berfungsi.
• Build rilis (Archive di Xcode, ./gradlew bundleRelease) berhasil, bukan hanya debug.

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

Rilis upgrade dengan aman menggunakan live updates

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

If you use Live updates Capgo, pisahkan pengguna Capacitor 7 dan Capacitor 8 sampai adopsi menyusul: tingkatkan versi native, upload bundle baru ke channel yang digunakan binary baru, dan jalankan cek 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 pengguna menerima update yang rusak.

Troubleshooting error upgrade Capacitor 8 yang umum

The engine "node" is incompatible atau CLI menolak untuk dijalankan. Anda menggunakan Node 20 atau lebih lama. Instal Node 22 LTS, dan perbarui juga image CI Anda.

error: invalid source release: 21 di Android. Gradle berjalan dengan JDK 17. Arahkan Android Studio ke JDK 21 bawaannya (Settings > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK) dan set 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. 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 dan plugin mana pun yang hardcode nilai itu.

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.