Come migrare la tua app Capacitor a Swift Package Manager

Swift Package Manager è la direzione predefinita per i progetti iOS Capacitor. Se la tua app usa ancora CocoaPods, puoi migrare l'app stessa a SPM senza ricostruire da zero il tuo code JavaScript, il progetto Android o il workflow di rilascio.

Questa guida è per i team di sviluppo app. Spiega come migrare un'app iOS Capacitor da CocoaPods a SPM, cosa cambia l'assistente di migrazione, cosa devi ancora verificare in Xcode e come ripulire la CI dopo che l'app è compilata.

Cosa cambia nell'app

Un'app Capacitor basata su CocoaPods dipende da file come:

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

Un'app Capacitor basata su SPM sposta la gestione delle dipendenze iOS in Swift Package Manager. Durante la migrazione, Capacitor crea un pacchetto locale chiamato CapApp-SPM e lo usa per collegare il target dell'app con Capacitor e le dipendenze native installate.

Il web build funziona ancora allo stesso modo. Esegui ancora un web build, sincronizzi Capacitor, apri Xcode e archivi l'app. La differenza principale è che CocoaPods non gestisce più il grafo delle dipendenze iOS.

Prima di migrare

Parti da un branch pulito e assicurati che l'app attuale compili prima di cambiare gestore delle dipendenze:

git status
npm run build
npx cap sync ios

Poi committa lo stato funzionante. La migrazione tocca i file del progetto iOS generati, quindi avere un punto di rollback pulito è importante.

Successivamente, verifica cosa ha personalizzato la tua app sotto ios/App/. I file e le impostazioni comuni da preservare includono:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, se presente
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, se usi Firebase
personalizzate .xcconfig file
impostazioni di firma, bundle identifier, team ID e profili di provisioning
estensioni dell'app, file Swift nativi, file Objective-C o framework incorporati

Controlla anche le dipendenze Capacitor e Cordova installate. Una migrazione SPM a livello di app può essere bloccata da una dipendenza nativa che non ha un percorso compatibile con SPM. Aggiorna quei pacchetti prima della migrazione, quando possibile.

Usa l'assistente di migrazione

Per la maggior parte delle app esistenti, parti dall'assistente di migrazione ufficiale di Capacitor:

npx cap spm-migration-assistant

Eseguilo dalla radice del tuo progetto Capacitor. L'assistente rimuove l'integrazione di CocoaPods, crea il locale CapApp-SPM pacchetto, genera riferimenti ai pacchetti per le dipendenze native installate e aggiunge la configurazione generata necessaria al progetto iOS.

Una volta completato, apri il progetto iOS:

npx cap open ios

Leggi l'output dell'assistente prima di chiudere il terminale. Se ti chiede di completare passaggi manuali in Xcode, esegui prima di sincronizzare di nuovo.

Completa i passaggi in Xcode

In Xcode, verifica la configurazione del progetto e del target dell'app:

Verifica CapApp-SPM viene aggiunto come dipendenza locale del pacchetto.
Verifica che il target dell'app colleghi i prodotti generati dal pacchetto.
Aggiungi quanto generato debug.xcconfig alla configurazione del progetto se l'assistente lo chiede.
Risolvi eventuali warning dei pacchetti in Xcode.
Esegui una build dell'app da Xcode.

Se Xcode non riesce a risolvere i pacchetti, usa File > Package > Reset Package Caches, quindi risolvi nuovamente i pacchetti.

Sincronizza e rifai la build

Dopo aver configurato Xcode, torna nel terminale e sincronizza Capacitor:

npx cap sync ios

Poi esegui di nuovo la build da Xcode. Non considerare conclusa la migrazione finché una build pulita non funziona da Xcode, perché la firma di release, gli entitlements, le app extension e la risoluzione dei pacchetti vengono validati proprio lì.

Se l'app usa notifiche push, associated domains, background modes, app groups, Firebase o qualsiasi configurazione nativa SDK, esegui quei flussi su un simulatore o dispositivo dopo che il build è andato a buon fine.

Alternativa: ricreare iOS con SPM

Se la tua ios/ cartella è vicina al template Capacitor predefinito, può essere più veloce ricrearla con SPM invece di migrarla sul posto.

Procedi solo dopo aver effettuato il commit o il backup di ogni file nativo e delle impostazioni di firma necessarie:

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

Poi ripristina i file e le impostazioni native specifiche della tua app. Questo metodo ti dà un progetto SPM pulito, ma è più facile perdere modifiche personalizzate a Xcode se prima non ne hai fatto un inventario.

Per le nuove app Capacitor, Capacitor 8 crea i progetti iOS con SPM di default:

npx cap add ios

Puoi comunque essere esplicito:

npx cap add ios --packagemanager SPM

Pulizia residui CocoaPods

Dopo il build dell'app con SPM, rimuovi i riferimenti residui a CocoaPods dagli script locali e dalla CI.

Rimuovi passaggi come:

pod install

Rimuovi anche le cache che esistevano solo per CocoaPods:

ios/App/Pods
ios/App/Podfile.lock
Repository delle specifiche CocoaPods
Chiavi di cache CI basate sul Podfile

Un flusso CI di base dopo la migrazione dovrebbe installare le dipendenze JavaScript, buildare l'app web, sincronizzare Capacitor e compilare con Xcode:

npm ci
npm run build
npx cap sync ios

Se la tua CI compila ancora App.xcworkspace, aggiornala al percorso del progetto o dello workspace esistente dopo la migrazione. Non mantenere vecchi percorsi CocoaPods solo perché il job precedente li usava.

Risoluzione problemi

L'assistente avverte di una dipendenza incompatibile

Aggiorna prima la dipendenza ed esegui di nuovo l'assistente. Se non esiste una versione compatibile con SPM, mantieni l'app su CocoaPods finché non sostituisci quella dipendenza o il maintainer non aggiunge il supporto SPM.

Xcode non riesce a risolvere i pacchetti

Reimposta le cache dei pacchetti in Xcode, verifica che CapApp-SPM sia presente come pacchetto locale ed esegui npx cap sync ios ancora.

L'app builda in locale ma la CI fallisce

Cerca eventuali vecchie assunzioni su CocoaPods: pod install, Pods/ cache, Podfile.lock cache key o comandi di build che puntano a un elemento eliminato .xcworkspace.

Signing o entitlements modificati

Confronta il target Xcode migrato con il progetto pre-migrazione. Ripristina bundle identifier, team, provisioning profile, file entitlements, capabilities e impostazioni delle extension.

Checklist di migrazione

Prima della migrazione:

Crea un branch.
Confirm the current iOS app builds.
Fai il commit dello stato funzionante.
Elenca i file nativi custom e le impostazioni di signing.
Aggiorna le dipendenze native che dispongono già di release SPM-compatibili più recenti.

Durante la migrazione:

Esegui npx cap spm-migration-assistant.
Apri il progetto con npx cap open ios.
Aggiungi CapApp-SPM in Xcode, se necessario.
Aggiungi debug.xcconfig in Xcode, se necessario.
Risolvi gli avvisi dei pacchetti.
Esegui npx cap sync ios.

Dopo la migrazione:

Compila l'app da Xcode.
Testa le funzionalità native su un simulatore o un dispositivo.
Rimuovi i comandi CocoaPods dalla CI.
Rimuovi le cache solo di CocoaPods.
Verifica l'archivio e la firma della release.

Usa le Capgo Skills per la migrazione

Se usi agenti AI per gestire la migrazione, parti da Competenze Capgo invece di un prompt vuoto. Le Skills più utili per questo lavoro sono:

capacitor-best-practices per rivedere la struttura dell'app prima di modificare ios/.
cocoapods-to-spm per pianificare la migrazione a SPM e i passaggi successivi su Xcode.
capacitor-ci-cd per rimuovere i presupposti su CocoaPods dalle pipeline di build.
debugging-capacitor e ios-android-logs per indagare i problemi specifici del dispositivo dopo la migrazione.

Usali prima di modificare il progetto iOS, così l'agent audita i file nativi, la CI e la compatibilità delle dipendenze, non solo esegue il comando di migrazione.

Conclusione

Migrare un'app Capacitor a Swift Package Manager è principalmente un cambio di gestione delle dipendenze iOS. Il percorso più sicuro è partire da una branch pulita ed eseguire npx cap spm-migration-assistant, completare i passaggi manuali in Xcode, sincronizzare di nuovo e rimuovere CocoaPods dalla CI solo dopo che l'app compila.

Se il tuo progetto iOS è molto personalizzato, migra in place. Se è vicino al template Capacitor predefinito, ricrea ios/ con npx cap add ios --packagemanager SPM può essere più pulito.