Come migrare un'app Capacitor a Swift Package Manager

Capacitor 8 crea nuovi progetti iOS con Swift Package Manager (SPM) di default. Anche le app esistenti che usano ancora CocoaPods possono migrare, ma la strada più sicura dipende da quanta personalizzazione nativa iOS ha la tua app.

Questa guida illustra cosa cambia, cosa salvare e i due percorsi pratici di migrazione: usare l'assistente di migrazione Capacitor o rigenerare lo scaffold del progetto iOS con SPM.

Perché migrare ora

CocoaPods si sta spostando verso un trunk in sola lettura. Il piano attuale prevede che il trunk di CocoaPods smetta di accettare nuovi podspec il 2 Dicembre 2026. Le build esistenti dovrebbero continuare a funzionare, ma i nuovi rilasci e gli aggiornamenti delle dipendenze basati su trunk non verranno pubblicati lì dopo il passaggio.

SPM è anche la direzione verso cui si sta muovendo Capacitor. Capacitor supporta la scelta tra CocoaPods o SPM fin dalla versione Capacitor 6, e Capacitor 8 ora crea progetti iOS SPM come template predefinito.

Cosa cambia in un progetto Capacitor con SPM

Passare da CocoaPods a SPM sostituisce lo strato di dipendenze iOS. L'app web, il progetto Android e la maggior parte dei comandi del workflow Capacitor rimangono invariati.

CapApp-SPM sostituisce il Podfile

In un'app CocoaPods, le dipendenze iOS sono collegate tramite ios/App/Podfile, Podfile.lock, Pods/, e il generato .xcworkspace.

In un'app SPM, Capacitor crea un package locale chiamato CapApp-SPM. Questo package diventa il punto centrale in cui Capacitor referenzia le dipendenze dei tuoi plugin nativi iOS. Gli aggiornamenti Capacitor CLI CapApp-SPM avvengono quando sincronizzi i plugin, quindi consideralo come output generato ed evita di modificarlo manualmente.

debug.xcconfig sostituisce la configurazione Pods

L'assistente di migrazione crea anche un file generato debug.xcconfig. Questo file contiene le impostazioni di build che CocoaPods forniva tramite i suoi file xcconfig generati.

Dopo la migrazione, potresti dover aggiungere debug.xcconfig alla configurazione del progetto Xcode se l'assistente te lo richiede.

Ogni plugin deve supportare SPM

Non puoi mixare CocoaPods e SPM nello stesso progetto iOS Capacitor. Prima di migrare, controlla ogni plugin Capacitor e Cordova in package.json.

Se un plugin non supporta ancora SPM, aggiornalo, sostituiscilo o migra prima il plugin. I semplici plugin Swift possono spesso essere convertiti con capacitor-plugin-converter, ma i plugin con strutture Objective-C e Swift più complesse potrebbero richiedere un lavoro manuale.

Cosa fare il backup per primo

Parti da un branch git pulito e fai il commit dello stato attuale prima di toccare il progetto iOS. Poi elenca i file nativi da cui dipende la tua app.

File comuni da preservare da ios/App/ inclusi:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, se la tua app ne ha uno
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, se usi Firebase
Personalizzato .xcconfig file
Impostazioni di firma, bundle identifier, team ID e provisioning profile

Preserva anche eventuali file nativi Swift, Objective-C, framework, extension o SDK aggiunti al di fuori del template standard Capacitor.

Opzione 1: usa l'assistente di migrazione Capacitor

Scegli questo percorso se il tuo progetto iOS contiene modifiche native personalizzate che non vuoi perdere.

Esegui l'assistente dalla root del tuo progetto Capacitor:

bunx cap spm-migration-assistant

L'assistente rimuove l'infrastruttura CocoaPods, crea il package CapApp-SPM locale, genera i riferimenti ai package dai plugin installati e crea i file di configurazione SPM generati.

Al termine, apri il progetto:

bunx cap open ios

Poi segui i passaggi manuali su Xcode indicati dall'assistente. Nella maggior parte dei progetti questo significa:

Aggiungi CapApp-SPM come dipendenza di un pacchetto locale.
Aggiungi il/la debug.xcconfig alla configurazione dell'app.
Risolvi eventuali warning sui plugin che non sono stati convertiti in SPM.
Esegui una build dell'app da Xcode prima di aggiornare la CI.

Dopo il build del progetto Xcode, esegui di nuovo la sync:

bunx cap sync ios

Opzione 2: Re-scaffold del progetto iOS con SPM

Usa questo percorso se la tua ios/ directory è simile al template Capacitor predefinito e puoi ripristinare i file personalizzati in sicurezza.

Per prima cosa, assicurati che i file elencati nella sezione backup siano commitati o copiati in un posto sicuro. Poi rimuovi e ricrea il progetto iOS con SPM:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

Ripristina i file nativi necessari alla tua app, quindi apri il progetto:

bunx cap open ios

Questo percorso è spesso più pulito di una migrazione in-place perché ti fornisce un nuovo template Capacitor 8 per iOS. Il compromesso è che dovrai riapplicare con cura signing, entitlements, file Firebase, modifiche al codice nativo e ogni impostazione personalizzata di Xcode.

Nuove app Capacitor

Per una nuova app, Capacitor 8 usa SPM di default quando aggiungi iOS:

bunx cap add ios

Se hai bisogno di essere esplicito, puoi comunque passare l'opzione del package manager:

bunx cap add ios --packagemanager SPM

Aggiorna la CI dopo la migrazione

Una volta che l'app è buildata localmente, aggiorna la CI/CD in modo che non richieda più CocoaPods.

Rimuovi i passaggi che eseguono:

pod install

Rimuovi anche le cache per:

ios/App/Pods
ios/App/Podfile.lock
I repository delle spec di CocoaPods, se il tuo workflow li ha in cache solo per questa app

Mantieni i soliti passaggi di web build e sync di Capacitor. Un tipico job iOS dovrebbe installare le dipendenze JavaScript, buildare gli asset web, sincronizzare Capacitor e poi buildare con Xcode:

bun install --frozen-lockfile
bun run build
bunx cap sync ios

Checklist di migrazione

Prima della migrazione:

Crea un nuovo branch git.
Fai il commit dell'app corrente.
Verifica che ogni plugin supporti SPM.
Annota i file iOS e le impostazioni di signing.
Conferma che l'app buildi prima della migrazione.

Durante la migrazione:

Esegui bunx cap spm-migration-assistant o esegui il re-scaffold ios/.
Aggiungi CapApp-SPM in Xcode, se necessario.
Aggiungi debug.xcconfig in Xcode, se necessario.
Ripristina i file nativi specifici dell'app.
Esegui bunx cap sync ios.

Dopo la migrazione:

Fai il build e avvia l'app in Xcode.
Rimuovi i file CocoaPods residui.
Rimuovi pod install dalla CI.
Verifica che la firma della release funzioni ancora.
Testa l'app su almeno un simulatore e un dispositivo reale prima del rilascio.

Risoluzione problemi

Se Xcode non riesce a risolvere i package, resetta le cache dei package da Xcode ed esegui bunx cap sync ios ancora.

Se la migrazione fallisce a causa di un plugin, verifica se il plugin ha una release più recente con supporto SPM. Per i plugin che mantieni, migra prima il pacchetto del plugin e poi torna alla migrazione dell'app.

Se l'app builda localmente ma la CI fallisce, controlla eventuali vecchi presupposti su CocoaPods. Le cause comuni sono un .xcworkspace percorso di build forzato, un pod install comando obsoleto o il Pods/ caching di build precedenti.

Conclusione

Migrare un'app Capacitor a Swift Package Manager consiste principalmente nel sostituire i collegamenti delle dipendenze iOS. CapApp-SPM gestisce i riferimenti alle dipendenze, debug.xcconfig sostituisce la configurazione di build generata da CocoaPods, e la CI non richiede più pod install.

Per i progetti iOS personalizzati, inizia con bunx cap spm-migration-assistant. Per i progetti vicini al template di default, un re-scaffold pulito con SPM è spesso più veloce e più facile da gestire.

Risorse

Continua da Come migrare un'app Capacitor a Swift Package Manager

Se stai usando Come migrare un'app Capacitor a Swift Package Manager per pianificare la migrazione e le operazioni enterprise, collegalo a Capgo Enterprise per il workflow del prodotto in Capgo Enterprise, Alternative ai plugin Ionic Enterprise per il workflow del prodotto nelle alternative ai plugin Ionic Enterprise, Alternative a Capgo per il workflow del prodotto in Capgo Alternatives, Consulenza Capgo per il workflow di prodotto in Capgo Consulting, e Supporto Premium Capgo per il workflow di prodotto in Capgo Premium Support.