Migration Capacitor 8 vers Capacitor 9 : Guide Complet, Breaking Changes, SPM, iOS 16 & Android Target SDK 37

Le résumé

• Capacitor 9 impose Node.js 24+ (avec npm 11) et introduit des exigences natives majeures pour iOS et Android.
• iOS : Cible minimale relevée à iOS 16.0, support Xcode 27, conformité Swift 6 obligatoire (remplacement de @UIApplicationMain par @main) et transition impérative vers Swift Package Manager (SPM) en prévision de la fermeture en lecture seule de CocoaPods Trunk fin 2026.
• Android : Cible relevée à Target SDK 37 (Android 16+), outillage Android Studio 2026.1, AGP 9.2.1, Gradle 9.5.1, fusion de core-ktx dans androidx.core:core 1.19.0 et suppression définitive de jcenter().
• Runtime Cordova : Le pont de compatibilité Cordova devient 100% optionnel. Si aucun plugin Cordova n'est détecté, le runtime Cordova n'est plus injecté dans vos projets natifs, allégeant drastiquement la taille du bundle APK / IPA.
• CLI & Live Reload : Les anciens flags -l, --host, --port sont fusionnés dans un flag unique cap run --url <DEV_SERVER_URL>.

Capacitor 9 marque une étape décisive dans l'histoire de l'écosystème hybride-natif. En rompant définitivement avec les résidus du legacy Cordova et en adoptant les standards modernes d'Apple (SPM, Swift 6) et de Google (AGP 9, Kotlin intégré), cette version garantit une conformité parfaite avec les exigences 2026 des stores. Ce guide rédigé par Julien Kermarec, expert certifié Ionic Developer Expert (IDE), vous détaille l'ensemble des ruptures et les étapes précises pour migrer votre application.

Réponse directe : quelles sont les ruptures majeures de Capacitor 9 ?

La mise à jour de Capacitor 8 vers Capacitor 9 n'est pas une simple montée de version mineure. Elle implique :

1. L'adoption de Swift Package Manager (SPM) en remplacement de CocoaPods sur iOS (CocoaPods Trunk passant en lecture seule en décembre 2026).
2. La mise à niveau de l'outillage Android vers AGP 9.2.1 et Gradle 9.5.1 avec compilation sous Target SDK 37.
3. L'isolation totale du runtime Cordova : les applications modernes 100% Capacitor bénéficient désormais d'un binaire natif épuré sans traces de code Apache Cordova.

1. Prérequis d'environnement de développement

Avant de lancer la migration de votre projet Capacitor, vous devez mettre à jour vos environnements locaux et vos pipelines d'intégration continue (CI/CD) :

| Outil | Version Minimale Capacitor 9 | Recommandation Kerweb | | :--- | :--- | :--- | | Node.js | >= 24.0.0 (npm 11+) | Node.js 24 LTS | | Xcode (macOS) | Xcode 27.0+ | macOS Sequoia / Tahoe | | Android Studio | Android Studio 2026.1.1+ | Ladybug / 2026 Feature Release | | Android Gradle Plugin | AGP 9.2.1 | Gradle Wrapper 9.5.1 | | iOS Deployment Target | iOS 16.0+ | Déprécie le support iOS 14 & 15 | | Android API Target | compileSdk 37 / targetSdk 37 | minSdk 26 (Android 8.0 Oreo) |

2. Breaking Changes iOS & Guide de Migration

2.1 Hausse du Deployment Target à iOS 16.0

Dans votre projet Xcode (ios/App/App.xcodeproj), sélectionnez votre Target principale et mettez à jour le iOS Deployment Target à 16.0. Si votre projet utilise encore CocoaPods, modifiez votre ios/App/Podfile :

platform :ios, '16.0'

2.2 Remplacement de @UIApplicationMain par @main (Swift 6)

Swift 6 (inclus dans Xcode 27) rejette formellement l'attribut historique @UIApplicationMain. Dans ios/App/App/AppDelegate.swift :

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

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

2.3 Migration de CocoaPods vers Swift Package Manager (SPM)

⚠️ IMPORTANT : CocoaPods Trunk passe en lecture seule en décembre 2026. Pour pérenniser vos applications, Kerweb recommande de convertir vos projets iOS vers SPM dès la mise à niveau vers Capacitor 9. Les nouveaux projets Capacitor 9 initialisent automatiquement SPM par défaut via Package.swift. Pour un projet existant, la commande npx cap migrate configure automatiquement les dépendances SPM pour les plugins officiels.

3. Breaking Changes Android & Guide de Migration

3.1 Nettoyage de gradle.properties

AGP 9 a supprimé les anciens flags de compatibilité. Ouvrez android/gradle.properties et supprimez les options dépréciées :

# Supprimez ces lignes obsolètes si elles sont présentes dans votre fichier :
- android.defaults.buildfeatures.resvalues=true
- android.sdk.defaultTargetSdkToCompileSdkIfUnset=false
- android.enableAppCompileTimeRClass=false
- android.builtInKotlin=false
- android.r8.strictFullModeForKeepRules=false
- android.newDsl=false

3.2 Mise à jour de variables.gradle (Target SDK 37)

Mettez à jour le fichier android/variables.gradle avec les nouvelles versions requises :

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 Fusion de core-ktx dans core & Suppression de jcenter()

androidx.core:core 1.19.0 intègre désormais nativement toutes les extensions Kotlin de core-ktx. Si votre projet ou un plugin tiers dépendait de core-ktx, remplacez-le par androidx.core:core :

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

Dans votre android/build.gradle, assurez-vous également que jcenter() a été remplacé par mavenCentral() :

repositories {
    google()
    mavenCentral()
}

4. Révolution de la CLI : Live Reload simplifié avec --url

Dans Capacitor 9, l'ensemble des flags d'émulation en direct (-l, --host, --port, --https) a été simplifié au profit d'un paramètre unique --url.

Au lieu de :

# Syntaxe obsolète (Capacitor 8)
npx cap run android -l --host 192.168.1.50 --port 5173

Utilisez directement l'URL affichée par votre serveur de développement Vite ou Next.js :

# Syntaxe moderne Capacitor 9
npx cap run android --url http://192.168.1.50:5173

5. Comment exécuter la migration pas à pas

Étape 1 : Installer la CLI Capacitor 9

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

Étape 2 : Lancer la commande de migration automatique

npx cap migrate

L'assistant interactif de Capacitor inspecte votre configuration, met à jour les dépendances dans package.json, adapte vos fichiers variables.gradle et convertit votre projet.

Étape 3 : Synchroniser les plateformes natives

npx cap sync

Étape 4 : Vérifier et compiler sur Xcode et Android Studio

npx cap open ios
npx cap open android

Dans Android Studio, utilisez Tools -> AGP Upgrade Assistant pour finaliser la bascule vers AGP 9.2.1 si nécessaire.

FAQ Technique sur la Migration Capacitor 9

Mon application fonctionne-t-elle encore si j'utilise des plugins Cordova ?

Oui. Capacitor 9 continue de supporter les plugins Cordova, mais le module natif Cordova n'est désormais injecté que si la commande npx cap sync détecte effectivement un plugin Cordova installé. Si vous n'en avez aucun, votre binaire est allégé et libéré de tout code Cordova.

Pourquoi est-il urgent de passer à Swift Package Manager (SPM) ?

Apple et la communauté iOS abandonnent progressivement CocoaPods. CocoaPods Trunk devient en lecture seule fin 2026. En adoptant SPM dès Capacitor 9, vous sécurisez vos builds natifs et accélérez considérablement vos temps de CI/CD.

Combien de temps nécessite la migration d'une application de production ?

Pour une application web standard (React, Vue, Next.js), la migration prend généralement entre 1 et 2 jours ouvrés (incluant les tests sur simulateurs et appareils réels). Pour les architectures complexes avec de nombreux plugins custom natifs, Kerweb propose un accompagnement expert sous 48h.