Préparer Capacitor 9 : ce que les équipes d'app et de plugins peuvent faire dès maintenant

Capacitor 9 est disponible sur la next dist-tag pendant sa phase de déploiement progressif. Vous n'êtes pas obligé de mettre à jour votre app dès la sortie de l'alpha, mais le guide officiel de mise à jour Capacitor 9 et guide de mise à jour des plugins détaille déjà les failles de la toolchain et les suppressions de API qu'il convient d'aborder tôt.

Cet article est une préparation checklist : travaillez sur Capacitor 8 (ou sur une branche) pour que la transition bunx cap migrate finale soit simple plutôt que douloureuse. Quand vous serez prêt pour la migration, suivez les guides d'Ionic liés ci-dessus ligne par ligne.

Faiblesses de la toolchain et des plateformes (apps)

Planifiez votre CI, vos machines locales et vos pipelines de stores autour de ces minimums :

Si vous utilisez encore Capacitor 8.4 ou une version antérieure pour iOS, vous aurez également besoin du cycle de vie UIScene issu de la mise à jour Capacitor 8.5 avant Cap 9 — Xcode 27 l'exige. Les apps déjà sous la version 8.5 peuvent ignorer cette étape.

Sur iOS, Swift 6 (avec Xcode 27) rejette @UIApplicationMain; lors de votre mise à niveau, remplacez-le par @main dans AppDelegate.swift comme décrit dans le guide officiel.

Cordova at app sync time (not a plugin prep step)

Avec Capacitor 9, la couche de compatibilité Cordova est uniquement intégrée à votre app quand cap sync détecte un plugin Cordova installé. Android supprime les modules Gradle supplémentaires lorsqu'aucun n'est présent ; iOS cesse d'ajouter CapacitorCordova au Podfile ou Package.swift lorsqu'aucun n'est présent.

Il s'agit d'un changement de comportement au niveau de l'app après la mise à niveau. Tant que vous êtes sur Cap 8, pas besoin de supprimer Cordova de votre template préventivement. Vérifiez si des code natifs personnalisés (les vôtres ou un plugin forké) importent des symboles Cordova sans plugin Cordova réel dans le projet — ces références échoueront une fois le câblage Cordova optionnel appliqué.

Android : gradle.properties et les paramètres par défaut d'AGP 9

L'AGP Upgrade Assistant écrit souvent des gradle.properties flags explicites pour conserver le comportement d'AGP 8. Les apps Capacitor 9 devraient supprimer ces entrées plutôt que de les conserver : la plupart sont obsolètes avant AGP 10, et certaines cassent les builds Cap 9 (par exemple, android.builtInKotlin=false désactive le support Kotlin inclus dans AGP 9, et android.sdk.defaultTargetSdkToCompileSdkIfUnset=false empêche AGP d'inférer targetSdkVersion).

Lors de la migration, prévoyez également de :

• Augmenter variables.gradle les minimums (compile/target SDK 37, minSdkVersion 26, versions AndroidX mises à jour — voir la doc officielle).
• Supprimer l'explicite targetSdkVersion depuis l'application build.gradle pour qu'AGP 9 puisse l'inférer depuis compileSdkVersion.
• Déclarer variables.gradle les symboles en haut de app/build.gradle (Gradle 9.6 déprécie la recherche implicite depuis le projet racine).
• Remplacer les noms de fichiers ProGuard par défaut, migrer core-ktx vers androidx.core:core 1.19.0+, abandonner l'usage du plugin Kotlin Gradle autonome, et supprimer jcenter().

Vous pouvez lire les diffs dans le Passage à la version 9.0 section Android et appliquer les mêmes nettoyages sur une branche avant de passer aux versions Capacitor.

CLI : cap run --url

Capacitor 9 fusionne les flags host/port/https du live reload en un seul --url argument. Au lieu de :

bunx cap run android -l --host 192.168.1.181 --port 5173

passez l'URL affichée par votre serveur de dev :

bunx cap run android --url http://192.168.1.181:5173/

Update scripts and README snippets now so muscle memory does not fight the new CLI after upgrade.

Plugins officiels : pièges push et splash

Deux changements côté utilisateur apparaissent souvent dans les apps en production :

Notifications push (iOS) : L'obsolescence de alert presentation dépréciée est supprimée. Utilisez banner et/ou list dans vos options de présentation.

Splash Screen (Android) : Par défaut launchFadeOutDuration changements de 200 ms à 0. If you relied on the fade hiding first paint glitches, set launchFadeOutDuration: 200 explicitement dans capacitor.config en attendant d'ajuster votre UI de démarrage.

Consultez les sections plugins dans le guide de mise à jour 9.0 pour les montées de version AndroidX et Google Play Services liées aux plugins officiels que vous utilisez.

Maintainers de plugins : préparez Cap 9 sans casser Cap 8

Si vous déployez Capacitor plugins utilisés sur Capacitor 8 et pour préparer code à Cap 9, concentrez-vous sur la suppression des API obsolètes, not on Cap-9-only packaging changes.

Safe to do while Cap 8 remains supported:

• Remplacer @NativePlugin par @CapacitorPlugin et migrez les anciennes API de permissions / activity-result vers des @PermissionCallback / @ActivityCallback patterns (consultez le guide du plugin 9.0 dans le tableau).
• Supprimer PluginCall.hasOption, Plugin.getConfigValue, anciens CapConfig constructeurs et getters, PluginCall.save() / isSaved(), et autres suppressions Java listées dans « Breaking changes in code ».
• Sur iOS, cessez d'utiliser la CAPBridge classe de compatibilité et les CAPBridgeProtocol helpers obsolètes ; utilisez ApplicationDelegateProxy, typed PluginCall typés et les propriétés de bridge du tableau de migration.
• Exécutez bunx @capacitor/plugin-migration-v8-to-v9@latest sur une branche et ne conservez que les modifications API qui compilent encore avec les peer dependencies de Cap 8 jusqu'à la publication d'une version majeure pour Cap 9.

Ne supprimez pas le Cordova produit SPM de votre plugin Package.swift tant que vous supportez encore Capacitor 8. Les projets Cap 8 attendent cette dépendance si votre plugin est basé sur SPM ; la supprimer trop tôt casse les utilisateurs encore sur la version 8. Traitez optionnel Cordova / supprimer l'inconditionnel Cordova produit comme Capacitor réservé à la version 9 la branche de release (ou une version majeure semver explicitement documentée comme Cap 9+), une fois que vous ne supportez plus Cap 8 — comme décrit dans le guide des plugins, et non comme préparation sur la branche Cap 8.

La même règle s'applique pour l'incrémentation de capacitor-swift-pm vers 9.0.0-alpha.x dans Package.swift: qui appartient à votre version majeure Cap 9, et non à une release compatible Cap 8.

Capgo live updates et le build natif Cap 9 pour les stores

Capgo livre des bundles web via des mises à jour OTA ; la coquille native provient toujours de l'App Store et de Google Play. Lorsque vous passez votre application à Capacitor 9 :

1. Déployer au moins un build store compilé avec des projets natifs Capacitor 9 (iOS et Android). Ce binaire établit la base native que les canaux Capgo visent.
2. Ce n'est qu'une fois ce build entre les mains des utilisateurs que vous devrez vous appuyer sur des bundles OTA testés avec le comportement de la WebView et des plugins de Cap 9.
3. Configurez vos canaux de production sur la metadata stratégie et envoyez le bundle Cap 9 correspondant à chaque canal avec --auto-min-update-version. Pour cet upload intentionnel de la base native, omettez --fail-on-incompatible (les packages natifs sont censés changer). Gardez --fail-on-incompatible et --auto-min-update-version des uploads OTA quotidiens par la suite. Voir Workflow du canal Native + OTA.
4. Alignez vos règles de canal et de semver pour ne jamais envoyer un bundle utilisant les API de Cap 9 à des appareils tournant encore sur une ancienne version native.

Si vous utilisez Build Capgo ou votre propre CI, rafraîchissez les agents avant la release store de Cap 9 pour que le pipeline corresponde à ce que les utilisateurs installent : machine macOS les runners nécessitent Node 24+ et Xcode 27+; Linux les runners nécessitent Node 24+ et des outils Android hôtes alignés sur AGP 9.2.1 / Gradle 9.5.1 (Xcode est disponible uniquement sur macOS).

Ordre d'opérations suggéré

1. Mettre à jour les outils installés sur les hôtes CI et les machines de développement vers les versions ci-dessus (Node, Xcode, Android Studio, JDK). Ne pas mettre à jour la dépendance AGP, le Gradle wrapper ou d'autres fichiers de projet Android de l'app Cap 8 vers les valeurs de Cap 9 avant que bunx cap migrate — ces changements de projet ne fassent partie de l'étape de migration.
2. Corriger les API natives obsolètes dans l'app code et les plugins (notamment les AppDelegate gestion des URL et l'usage du bridge Android).
3. Nettoyer Android Gradle fichiers et scripts (gradle.properties, les paramètres ProGuard, --url dans les scripts de dev).
4. Auditer l'usage de Cordova au niveau de l'app ; ne modifiez pas les produits Cordova SPM jusqu'aux releases dédiées à Cap 9.
5. Quand Cap 9 sera en GA (ou quand vous accepterez next), lancez bun add -d @capacitor/cli@next (ou @latest après la release), puis bunx cap migrate, et suivez Passage à la version 9.0.
6. Publiez le build natif Cap 9 sur les stores, puis reprenez ou étendez les déploiements progressifs Capgo OTA sur le canal correspondant.

Capacitor 9 consiste surtout à « réduire la dette technique et s'aligner sur les toolchains modernes d'Android et d'Apple ». Effectuer ce travail sur Cap 8 permet de limiter la taille du diff de mise à jour et de garder vos plugins compatibles avec les équipes qui publient encore la version 8.x aujourd'hui.