Preparing for Capacitor 9: What App and Plugin Teams Can Do Now

Capacitor 9 is available on the next Vous n'avez pas besoin d'actualiser votre application dès que l'alpha est disponible, mais official Capacitor 9 update guide et Guide d'actualisation de plugin Déjà détailler les outils de chaîne de fabrication et les suppressions de API qui valent la peine d'être traitées tôt.

Cet article est un préparation liste de tâches : travail que vous pouvez effectuer sur Capacitor 8 (ou sur une branche) afin que les futures bunx cap migrate La passe est monotone plutôt que douloureuse. Lorsque vous êtes prêt à passer à l'étape suivante, suivez les guides d'Ionic ci-dessus ligne après ligne.

Plateformes et sols de chaîne d'outils (apps)

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

If vous êtes toujours sur Capacitor 8.4 ou antérieur pour iOS, vous avez également besoin de Cycle de vie de la vue d'interface Travaillez à partir de la mise à jour Capacitor 8.5 avant Cap 9 — Xcode 27 l'exige. Les applications déjà sur 8.5 peuvent sauter cette étape supplémentaire.

Sur iOS, Swift 6 (avec Xcode 27) rejette @UIApplicationMain; lorsque vous mettez à jour, remplacez-le par @main en AppDelegate.swift comme décrit dans le guide officiel.

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

Dans Capacitor 9, la couche de compatibilité Cordova est seulement branchée à votre application lorsque cap sync détecte un plugin Cordova installé. Android supprime les modules Gradle supplémentaires lorsque aucun n'est présent; iOS arrête d'ajouter CapacitorCordova à la Podfile ou Package.swift lorsqu'aucune n'est présente.

C'est une app-level behavior change after you upgrade. While you are still on Cap 8, you do not need to rip Cordova out of your template preemptively. Do audit whether any custom native code (yours or a forked plugin) imports Cordova symbols without an actual Cordova plugin in the project — those references will fail once optional Cordova wiring applies.

Android: gradle.properties et AGP 9 par défaut

L'assistant de mise à niveau AGP écrit souvent explicitement gradle.properties Les drapeaux gardent le comportement AGP 8. Capacitor les applications 9 devraient remove Au lieu de les conserver, la plupart sont obsolètes avant AGP 10, et certaines cassent les builds de Cap 9 (par exemple) android.builtInKotlin=false empêche le support Kotlin que AGP 9 embarque, et android.sdk.defaultTargetSdkToCompileSdkIfUnset=false arrête AGP d'inférer targetSdkVersion).

Lorsque vous migrez, attendez-vous également à :

• Augmenter variables.gradle les minimums (compile/cible SDK 37, minSdkVersion 26, les versions mises à jour d'AndroidX — voir la doc officielle).
• Supprimer les déclarations explicites targetSdkVersion du module build.gradle afin que AGP 9 puisse l'inférer à partir de compileSdkVersion.
• Déclarer variables.gradle les symboles en haut de app/build.gradle (Gradle 9.6 déprecie l'implémentation implicite de recherche à partir du projet racine).
• Échangez les noms par défaut des fichiers ProGuard, migrez core-ktx à androidx.core:core 1.19.0+, abandonnez l'utilisation du plugin Gradle Kotlin en standalone et supprimez jcenter().

Vous pouvez lire les diff hunks dans la Mise à jour vers 9.0 section Android et appliquez les mêmes nettoyages sur une branche avant de faire passer les versions Capacitor.

CLI : cap run --url

Capacitor 9 intègre les drapeaux de live-reload host/port/https en un seul --url argument. Au lieu de :

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

pass the URL your dev server prints:

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

Mettez à jour les scripts et les extraits README maintenant pour que la mémoire musculaire ne s'oppose pas au nouveau CLI après mise à niveau.

Plugins officiels : les pièges de push et splash

Two user-facing changes show up often in production apps:

Notifications Push (iOS) : La fonction obsolète alert L'option de présentation est supprimée. Utilisez banner et/ou list Écran de Splash (Android) :

La valeur par défaut passe de à launchFadeOutDuration mises à jour 200 ms à 0Si vous vous appuyiez sur le fade pour cacher les premiers glitches de peinture, launchFadeOutDuration: 200 explicitement dans capacitor.config until you adjust your startup UI.

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

Mainteneurs de plugin : préparez-vous sur Cap 8 sans casser Cap 8

Si vous distribuez des Capacitor plugins consommés sur Capacitor 8 et veulent un code prêt à Capacitor 9, concentrez-vous sur vouliez-vous que API soit prêt pour Cap 9, concentrez-vous surla suppression des __CAPGO_KEEP_0__ obsolètes

Sécurisé tant que Cap 8 reste pris en charge :

• Remplacez @NativePlugin par @CapacitorPlugin et migrez les anciens APIs de permission / activity-result vers @PermissionCallback / @ActivityCallback les modèles (voir la guide du plugin 9.0 ).
• Supprimez PluginCall.hasOption, Plugin.getConfigValue, les anciens CapConfig constructeurs et les getters, PluginCall.save() / isSaved(), et les autres suppressions de Java listées sous « Changements de rupture dans code ».
• Sur iOS, arrêtez d'utiliser la CAPBridge classe de compatibilité et les dépréciés CAPBridgeProtocol Les aides ; utilisez ApplicationDelegateProxy, saisie PluginCall les accesseurs et les propriétés de pont de la table de migration.
• Exécutez bunx @capacitor/plugin-migration-v8-to-v9@latest on a branch and keep only the API edits that still compile against Cap 8 peer dependencies until you publish a major for Cap 9.

Ne supprimez pas le Cordova Produit SPM de votre plugin Package.swift pendant que vous continuez à supporter Capacitor 8. Les projets Cap 8 attendent cette dépendance lorsque votre plugin est basé sur SPM ; la supprimer tôt brise les consommateurs qui sont encore sur 8. tant que vous soutenez encore __CAPGO_KEEP_0__ 8. Cordova product comme un Capacitor 9-seul la ligne de versionnement de sortie (ou une version majeure de semver explicitement documentée comme Cap 9+), après avoir cessé de soutenir Cap 8 — comme décrit dans la notice du plugin, et non comme travail de préparation sur la ligne Cap 8.

La même règle de doigté s'applique à l'augmentation capacitor-swift-pm à 9.0.0-alpha.x in Package.swiftCela devrait figurer dans votre mise à jour majeure Cap 9, pas dans une mise à jour compatible Cap-8.

Capgo live updates and the native Cap 9 store build

Capgo livre des solutions bundle web Mises à jour sur air; la coquille native provient toujours de l'App Store et Google Play. Lorsque vous déplacez votre application vers Capacitor 9:

1. Ship au moins une build de magasin compilé contre Capacitor 9 projets natifs (iOS et Android). Cette version établit la base native Capgo des canaux ciblés.
2. Ne vous appuyez que sur les mises à jour OTA testées contre Cap 9 WebView et le comportement des plugins après que cette mise à jour est parvenue aux utilisateurs.
3. Mettez les canaux de production sur le metadata Pour cette mise à jour native basée sur une intention, omettez --auto-min-update-versionPour cette mise en ligne native intentionnelle. omit --fail-on-incompatible Flux de travail de canal natif + OTA --fail-on-incompatible and --auto-min-update-version Ensuite, voir les mises à jour OTA quotidiennes. Flux de travail de canal natif + OTA.
4. Keep channel and semver rules aligned so you never push a bundle that assumes Cap 9 APIs to devices still running an older native shell.

Si vous utilisez Capgo Build ou votre propre CI, agents de mise à jour avant avant de travailler sur une nouvelle fonctionnalité, mentionnez l'incident macOS runners nécessitent Node 24+ et Xcode 27+; Xcode 27+ runners nécessitent Node 24+ et outillage Android d'hôte aligné avec les exécutants nécessitent Node 24+ et outillage Android d'hôte aligné sur (Xcode est réservé à macOS).

(Xcode est réservé à macOS).

1. Mettre à jour les outils installés sur les hôtes CI et les machines de développement jusqu'aux versions supérieures (Node, Xcode, Android Studio, JDK). Ne pas augmenter la dépendance AGP de l'application Cap 8, le wrapper Gradle ou d'autres fichiers de projet Android jusqu'aux valeurs de Cap 9 avant bunx cap migrate — ces modifications de projet appartiennent à l'étape de migration.
2. Réparer les API natives obsolètes en application code et plugins (notamment personnalisés) AppDelegate Nettoyer les fichiers et les scripts Gradle Android
3. et les fichiers ( par défaut ProGuard,gradle.propertiesdans les scripts de développement). --url (in les scripts de développement).
4. Vérification de Cordova Utilisez-l’au niveau de l'application ; ne modifiez pas les plugins SPM des produits Cordova avant les sorties Cap 9 uniquement.
5. Lorsque Cap 9 est disponible (ou lorsque vous acceptez next), exécutez bun add -d @capacitor/cli@next (ou @latest après la mise à jour. bunx cap migrateet suivez , et suivez.
6. Publiez la mise en production native de Cap 9 à magasins, puis reprendre ou étendre Capgo les mises à jour OTA sur le canal correspondant.

Capacitor 9 is mostly “pay down deprecations and align with modern Android and Apple toolchains.” Doing that work on Cap 8 keeps your upgrade diff small and your plugins compatible with the teams still shipping 8.x today.