Prepararsi per Capacitor 9: cosa possono fare ora i team di app e plugin

Capacitor 9 è disponibile su next dist-tag mentre si avvicina alla disponibilità generale. Non è necessario aggiornare l'app il giorno del rilascio alpha, ma la guida ufficiale all'aggiornamento di Capacitor 9 e guida all'aggiornamento dei plugin abbiamo già elencato i limiti della toolchain e le rimozioni di API che conviene affrontare subito.

Questo articolo è una checklist di preparazione: attività da svolgere su Capacitor 8 (o su un branch) per rendere l'eventuale bunx cap migrate passaggio semplice invece che doloroso. Quando sarai pronto per il cutover, segui le guide di Ionic linkate sopra riga per riga.

Limiti di toolchain e piattaforma (app)

Pianifica CI, macchine locali e pipeline di rilascio basandoti su questi requisiti minimi:

Se per iOS utilizzi ancora Capacitor 8.4 o versioni precedenti, ti serve anche il ciclo di vita UIScene introdotto con l'aggiornamento Capacitor 8.5 prima di Cap 9 — Xcode 27 lo richiede. Le app già su 8.5 possono saltare questo passaggio.

Su iOS, Swift 6 (con Xcode 27) rifiuta @UIApplicationMain; quando aggiorni, sostituiscilo con @main in AppDelegate.swift come descritto nella guida ufficiale.

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

In Capacitor 9, il layer di compatibilità Cordova viene collegato alla tua app solo quando cap sync rileva un plugin Cordova installato. Android rimuove i moduli Gradle extra se non sono presenti; iOS smette di aggiungere CapacitorCordova al Podfile o Package.swift quando non sono presenti.

Si tratta di un cambiamento di comportamento a livello app dopo l'upgrade. Finché rimani su Cap 8, non devi rimuovere Cordova dal template in anticipo. Controlla però se eventuali code nativo personalizzato (tuoi o di un plugin forkato) importano simboli Cordova senza un plugin Cordova reale nel progetto — tali riferimenti falliranno una volta applicato il wiring opzionale di Cordova.

Android: gradle.properties e i default di AGP 9

L'AGP Upgrade Assistant spesso scrive flag espliciti gradle.properties per mantenere il comportamento di AGP 8. Le app con Capacitor 9 dovrebbero rimuovere quelle voci invece di mantenerle: la maggior parte è deprecata in vista di AGP 10, e alcune bloccano i build di Cap 9 (ad esempio android.builtInKotlin=false disabilita il supporto Kotlin incluso in AGP 9, e android.sdk.defaultTargetSdkToCompileSdkIfUnset=false impedisce ad AGP di inferire targetSdkVersion).

Durante la migrazione, preparati anche a:

• Aggiornare variables.gradle i minimi (compile/target SDK 37, minSdkVersion 26, versioni AndroidX aggiornate — vedi la doc ufficiale).
• Rimuovi l'esplicito targetSdkVersion from the app build.gradle così AGP 9 può inferirlo da compileSdkVersion.
• Dichiara variables.gradle i simboli in cima a app/build.gradle (Gradle 9.6 depreca il lookup implicito dal root project).
• Cambia i nomi dei file ProGuard predefiniti, migra core-ktx a androidx.core:core 1.19.0+, abbandona l'uso del plugin Kotlin Gradle standalone e rimuovi jcenter().

Puoi leggere i diff hunks in Aggiornamento alla versione 9.0 sezione Android e applica le stesse pulizie su un branch prima di aggiornare le versioni di Capacitor.

CLI: cap run --url

Capacitor 9 unifica i flag live-reload host/port/https in un unico --url argomento. Invece di:

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

passa l'URL stampato dal tuo dev server:

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

Aggiorna ora script e snippet del README per evitare che la memoria muscolare contrasti il nuovo CLI dopo l'upgrade.

Plugin ufficiali: criticità con push e splash

Due cambiamenti lato utente compaiono spesso nelle app in produzione:

Notifiche Push (iOS): Il deprecato alert di presentazione deprecata è stata rimossa. Usa banner e/o list nelle tue opzioni di presentazione.

Splash Screen (Android): Predefinito launchFadeOutDuration cambia da 200 ms a 0. Se facevi affidamento sul fade per nascondere i glitch del first paint, imposta launchFadeOutDuration: 200 esplicitamente in capacitor.config finché non sistemi la tua UI di startup.

Controlla le sezioni dei plugin nella guida all'aggiornamento 9.0 per gli aggiornamenti di AndroidX e Google Play Services legati ai plugin ufficiali che usi.

Maintainer dei plugin: preparati a Cap 9 senza rompere Cap 8

Se distribuisci plugin Capacitor usati su Capacitor 8 e Vuoi preparare code per Cap 9? Concentrati su rimozione di API deprecati, non sui cambiamenti di packaging di Cap 9.

Puoi farlo in sicurezza mentre Cap 8 è ancora supportato:

• Sostituisci @NativePlugin con @CapacitorPlugin e migra le vecchie API permission / activity-result a @PermissionCallback / @ActivityCallback nuovi pattern (vedi la guida al plugin 9.0 nella tabella).
• Rimuovi PluginCall.hasOption, Plugin.getConfigValue, vecchi CapConfig costruttori e getter, PluginCall.save() / isSaved(), e altre rimozioni Java elencate in “Modifiche incompatibili in code”.
• Su iOS, smetti di usare la CAPBridge classe di compatibilità e gli CAPBridgeProtocol helper deprecati; usa ApplicationDelegateProxy, typed PluginCall e proprietà bridge dalla tabella di migrazione.
• Esegui bunx @capacitor/plugin-migration-v8-to-v9@latest su un branch e mantieni solo le modifiche API che compilano ancora con le peer dependencies di Cap 8, finché non pubblichi una major per Cap 9.

Non rimuovere il Cordova prodotto SPM dal tuo plugin Package.swift mentre supporti ancora Capacitor 8. I progetti con Cap 8 si aspettano quella dipendenza se il plugin è basato su SPM; rimuoverla troppo presto bloccherebbe chi è ancora sulla versione 8. Tratta opzionale Cordova / rimuovendo l'uncondizionale Cordova prodotto come un Capacitor solo per 9 release line (o un major semver esplicitamente documentato come Cap 9+), dopo aver smesso di supportare Cap 8 — come descritto nella guida ai plugin, non come lavoro preparatorio sulla linea Cap 8.

La stessa regola si applica all'aggiornamento di capacitor-swift-pm a 9.0.0-alpha.x in Package.swift: che appartiene alla tua major Cap 9, non a una release compatibile con Cap 8.

Capgo live updates e la build nativa per il Cap 9 store

Capgo distribuisce web bundle aggiornamenti over the air; la shell nativa proviene comunque dall'App Store e da Google Play. Quando passerai la tua app a Capacitor 9:

1. Rilascia almeno una build per lo store compilata con progetti nativi Capacitor 9 (iOS e Android). Quel binario stabilisce la baseline nativa per i canali Capgo.
2. Solo dopo che quella build è nelle mani degli utenti dovresti affidarti ai bundle OTA testati con il WebView e il comportamento dei plugin di Cap 9.
3. Imposta i canali di produzione sulla metadata strategia e carica il bundle Cap 9 corrispondente su ogni canale con --auto-min-update-version. Per quel caricamento intenzionale della baseline nativa, ometti --fail-on-incompatible (i pacchetti nativi dovrebbero cambiare). Mantieni --fail-on-incompatible e --auto-min-update-version dagli upload OTA quotidiani. Vedi Workflow canale Native + OTA.
4. Mantieni allineati canale e regole semver per evitare di pushare bundle che richiedono le API di Cap 9 su dispositivi con un native shell più vecchio.

Se utilizzi Build Capgo o la tua CI, aggiorna gli agenti prima del rilascio dello store di Cap 9, così la pipeline corrisponderà a ciò che installano gli utenti: macOS i runner richiedono Node 24+ e Xcode 27+; Linux i runner richiedono Node 24+ e gli strumenti Android devono essere allineati con AGP 9.2.1 / Gradle 9.5.1 (Xcode è disponibile solo su macOS).

Ordine operativo consigliato

1. Aggiorna gli strumenti installati sui server CI e sulle macchine di sviluppo alle versioni indicate (Node, Xcode, Android Studio, JDK). Non aggiornare la dipendenza AGP, il Gradle wrapper o altri file del progetto Android dell'app Cap 8 ai valori di Cap 9 finché bunx cap migrate — tali modifiche al progetto appartengono alla fase di migrazione.
2. Correggi le API native deprecate nell'app code e nei plugin (specialmente quelli custom AppDelegate gestione URL e uso del bridge Android).
3. Pulizia Android Gradle file e script (gradle.properties, impostazioni predefinite ProGuard, --url negli script di dev).
4. Audit di Cordova a livello di app; non modificare i prodotti Cordova SPM dei plugin fino al rilascio di Cap 9.
5. Quando Cap 9 sarà GA (o quando accetterai next), esegui bun add -d @capacitor/cli@next (o @latest dopo il rilascio), quindi bunx cap migrate, e segui Aggiornamento alla versione 9.0.
6. Pubblica il Native Build di Cap 9 negli store, poi riprendi o espandi i rollout OTA di Capgo sul canale corrispondente.

Capacitor 9 consiste principalmente nel "ridurre le deprecazioni e allinearsi ai modern toolchain di Android e Apple". Fare questo lavoro su Cap 8 mantiene piccolo il diff di upgrade e i tuoi plugin compatibili con i team che usano ancora la versione 8.x.