Capacitor 8 to Capacitor 9 Migration Guide: Breaking Changes, SPM, iOS 16 & Android Target SDK 37 — Kerweb Blog

Summary

Capacitor 9 requires Node.js 24+ (with npm 11) and introduces major native requirements for both iOS and Android.
iOS: Minimum deployment target raised to iOS 16.0, Xcode 27 support, mandatory Swift 6 compliance (replacing @UIApplicationMain with @main), and an essential transition to Swift Package Manager (SPM) ahead of CocoaPods Trunk becoming read-only in December 2026.
Android: Target SDK raised to Target SDK 37 (Android 16+), Android Studio 2026.1, AGP 9.2.1, Gradle 9.5.1, core-ktx merged into androidx.core:core 1.19.0, and permanent removal of jcenter().
Cordova Runtime: The legacy Cordova compatibility layer is now 100% optional. If no Cordova plugin is installed, the Cordova runtime is completely omitted, resulting in smaller APK / IPA bundle sizes.
CLI & Live Reload: Legacy flags -l, --host, --port are merged into a single streamlined flag cap run --url <DEV_SERVER_URL>.

Capacitor 9 marks a major evolutionary milestone in hybrid-native app development. By cutting legacy Cordova dependencies and embracing modern Apple (SPM, Swift 6) and Google (AGP 9, native Kotlin) architectures, it ensures strict compliance with 2026 App Store and Google Play guidelines. Written by Julien Kermarec, certified Ionic Developer Expert (IDE), this guide walks you through every breaking change and migration step.

Direct Answer: What are the primary breaking changes in Capacitor 9?

Upgrading from Capacitor 8 to Capacitor 9 requires addressing four core technical shifts:

Adopting Swift Package Manager (SPM) on iOS, replacing CocoaPods before CocoaPods Trunk becomes read-only in December 2026.
Upgrading Android build tools to AGP 9.2.1, Gradle 9.5.1, and Target SDK 37.
Decoupling the Cordova runtime: modern pure-Capacitor applications now produce clean native binaries without Apache Cordova overhead.
Adopting Node.js 24+ across all development machines and CI/CD pipelines.

1. Development Environment Prerequisites

Before starting your project migration, update your local tooling and CI/CD runners:

2. iOS Breaking Changes & Migration Guide

2.1 Raise Deployment Target to iOS 16.0

In Xcode (ios/App/App.xcodeproj), select your primary target and update the iOS Deployment Target to 16.0. If your project still uses CocoaPods, update ios/App/Podfile:

platform :ios, '16.0'

2.2 Replace @UIApplicationMain with @main (Swift 6)

Swift 6 (bundled with Xcode 27) rejects @UIApplicationMain. In ios/App/App/AppDelegate.swift:

// Before (Capacitor 8)
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate { ... }

// After (Capacitor 9)
@main
class AppDelegate: UIResponder, UIApplicationDelegate { ... }

2.3 Migrate CocoaPods to Swift Package Manager (SPM)

⚠️ IMPORTANT: CocoaPods Trunk becomes read-only in December 2026. Kerweb strongly recommends migrating your Capacitor iOS projects to SPM during this upgrade. New Capacitor 9 projects use SPM by default via Package.swift. For existing apps, npx cap migrate automatically configures official plugins via SPM.

3. Android Breaking Changes & Migration Guide

3.1 Clean up gradle.properties

AGP 9 removes legacy compatibility flags. In android/gradle.properties, remove deprecated flags:

# Remove obsolete flags if present:
- android.defaults.buildfeatures.resvalues=true
- android.sdk.defaultTargetSdkToCompileSdkIfUnset=false
- android.enableAppCompileTimeRClass=false
- android.builtInKotlin=false
- android.r8.strictFullModeForKeepRules=false
- android.newDsl=false

3.2 Update variables.gradle (Target SDK 37)

Update android/variables.gradle with the new minimum versions:

ext {
    minSdkVersion = 26
    compileSdkVersion = 37
    targetSdkVersion = 37
    androidxActivityVersion = '1.13.0'
    androidxAppCompatVersion = '1.7.1'
    androidxCoordinatorLayoutVersion = '1.3.0'
    androidxCoreVersion = '1.19.0'
    androidxFragmentVersion = '1.8.9'
    coreSplashScreenVersion = '1.2.0'
    androidxWebkitVersion = '1.16.0'
    junitVersion = '4.13.2'
    androidxJunitVersion = '1.3.0'
    androidxEspressoCoreVersion = '3.7.0'
    cordovaAndroidVersion = '15.0.0'
}

3.3 Merge core-ktx into core & Remove jcenter()

androidx.core:core 1.19.0 merges all Kotlin extensions previously shipped in core-ktx. Replace core-ktx with core:

dependencies {
    implementation "androidx.core:core:1.19.0"
}

In android/build.gradle, verify that jcenter() has been replaced with mavenCentral():

repositories {
    google()
    mavenCentral()
}

4. Simplified CLI: Live Reload with `--url`

Capacitor 9 merges live-reload flags into a single --url argument:

# Modern Capacitor 9 Syntax
npx cap run android --url http://192.168.1.50:5173

5. Step-by-Step Migration Process

Step 1: Install Capacitor 9 CLI

npm install -D @capacitor/cli@next @capacitor/core@next

Step 2: Run Automatic Migration

npx cap migrate

Step 3: Synchronize Native Platforms

npx cap sync

Step 4: Open in Xcode and Android Studio

npx cap open ios
npx cap open android

Frequently Asked Questions

Do Cordova plugins still work in Capacitor 9?

Yes. Capacitor 9 maintains backward compatibility with Cordova plugins, but only injects the Cordova native bridge when npx cap sync detects active Cordova plugins.

Why is migrating to SPM critical?

CocoaPods Trunk will become read-only in December 2026. Adopting SPM guarantees long-term maintainability and substantially faster CI/CD compilation speeds.

Need assistance with your enterprise migration?

For production applications with complex native bridge dependencies, Kerweb provides 48h emergency upgrade support.