Comment migrer votre application Capacitor vers Swift Package Manager

Swift Package Manager est l'approche par défaut pour les projets iOS Capacitor. Si votre app utilise encore CocoaPods, vous pouvez migrer l'app elle-même vers SPM sans reconstruire de zéro votre code JS, votre projet Android ou votre workflow de release.

Ce guide s'adresse aux équipes qui développent des apps. Il explique comment migrer une app iOS Capacitor de CocoaPods vers SPM, ce que l'assistant de migration modifie, ce qu'il vous reste à vérifier dans Xcode et comment nettoyer votre CI une fois l'app compilée.

Ce qui change dans l'app

Une app Capacitor basée sur CocoaPods dépend de fichiers tels que :

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

Une application Capacitor basée sur SPM déplace le câblage des dépendances iOS vers Swift Package Manager. Lors de la migration, Capacitor crée un package local nommé CapApp-SPM et l'utilise pour lier la cible de l'application à Capacitor et aux dépendances natives installées.

Le build web fonctionne toujours de la même manière. Vous lancez toujours un build web, synchronisez Capacitor, ouvrez Xcode et archivez l'application. La principale différence est que CocoaPods ne gère plus le graphe de dépendances iOS.

Avant de migrer

Partez d'une branche propre et assurez-vous que l'application actuelle compile avant de changer de gestionnaire de dépendances :

git status
npm run build
npx cap sync ios

Commitez ensuite l'état actuel. La migration modifie des fichiers de projet iOS générés, il est donc crucial d'avoir un point de rollback propre.

Ensuite, examinez les personnalisations de votre application sous ios/App/. Les fichiers et paramètres courants à préserver incluent :

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, si présent
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, si vous utilisez Firebase
personnalisés .xcconfig fichiers
paramètres de signature, identifiant de bundle, ID d’équipe et profils de provisionnement
extensions d’app, fichiers Swift natifs, fichiers Objective-C ou frameworks intégrés

Vérifiez également vos dépendances Capacitor et Cordova installées. Une migration SPM au niveau de l’app peut être bloquée par une dépendance native sans chemin compatible SPM. Mettez à jour ces packages avant la migration si possible.

Utiliser l'assistant de migration

Pour la plupart des applications existantes, commencez par l’assistant de migration officiel Capacitor :

npx cap spm-migration-assistant

Lancez-le depuis la racine de votre projet Capacitor. L’assistant supprime l’intégration CocoaPods et crée le local CapApp-SPM package, génère les références de package pour les dépendances natives installées et ajoute la configuration générée requise par le projet iOS.

Une fois terminé, ouvrez le projet iOS :

npx cap open ios

Lisez la sortie de l’assistant avant de fermer votre terminal. S’il vous demande d’effectuer des étapes manuelles dans Xcode, faites-l’avant de resynchroniser.

Terminer les étapes Xcode

Dans Xcode, vérifiez la configuration du projet et de la cible de l’application :

Confirmer CapApp-SPM est ajouté en tant que dépendance de package local.
Vérifiez que la cible de l’application lie les produits du package généré.
Add the generated debug.xcconfig à la configuration du projet si l’assistant vous le demande.
Résolvez les avertissements de package dans Xcode.
Compilez l’application une fois depuis Xcode.

If Xcode cannot resolve packages, use File > Packages > Reset Package Caches, puis résolvez à nouveau les packages.

Synchroniser et compiler à nouveau

Une fois Xcode configuré, revenez au terminal et synchronisez Capacitor :

npx cap sync ios

Puis relancez un build depuis Xcode. Ne considérez pas la migration comme terminée tant qu'un build propre ne passe pas depuis Xcode, car la signature de release, les entitlements, les extensions d'app et la résolution des packages y sont validés.

Si l'application utilise des notifications push, des domaines associés, des modes d'arrière-plan, des groupes d'app, Firebase ou toute configuration native SDK, testez ces parcours sur un simulateur ou un appareil une fois le build réussi.

Alternative : recréer l'app iOS avec SPM

Si votre ios/ dossier est proche du template Capacitor par défaut, il peut être plus rapide de le recréer avec SPM plutôt que de migrer en place.

N'utilisez cette approche qu'après avoir commité ou sauvegardé tous les fichiers natifs et paramètres de signature dont vous avez besoin :

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

Puis restaurez vos fichiers et paramètres natifs spécifiques à l'app. Cette approche vous donne un projet SPM propre, mais il est plus facile de perdre des modifications Xcode personnalisées si vous n'en avez pas fait l'inventaire avant.

Pour les nouvelles applications Capacitor, Capacitor 8 crée des projets iOS avec SPM par défaut :

npx cap add ios

Vous pouvez aussi être explicite :

npx cap add ios --packagemanager SPM

Nettoyer les résidus de CocoaPods

Une fois le build de l’app SPM terminé, supprimez les hypothèses liées à CocoaPods des scripts locaux et de la CI.

Supprimez des étapes comme :

pod install

Supprimez aussi les caches qui n’existaient que pour CocoaPods :

ios/App/Pods
ios/App/Podfile.lock
Dépôts de specs CocoaPods
Clés de cache CI basées sur le Podfile

Un flux CI de base après migration doit installer les dépendances JavaScript, compiler l'application web, synchroniser Capacitor et compiler avec Xcode :

npm ci
npm run build
npx cap sync ios

Si votre CI compile toujours App.xcworkspace, mettez-l’à jour avec le chemin du projet ou du workspace qui existe après la migration. Ne conservez pas d'anciens chemins CocoaPods simplement parce que l'ancien job les utilisait.

Troubleshooting

L'assistant signale une dépendance incompatible

Mettez d'abord la dépendance à jour et relancez l'assistant. Si aucune version compatible SPM n'existe, gardez l'app sur CocoaPods jusqu'à ce que vous remplaciez cette dépendance ou que le mainteneur ajoute le support SPM.

Xcode ne peut pas résoudre les packages

Réinitialisez les caches de packages dans Xcode, vérifiez que CapApp-SPM est présent en tant que package local, et lancez npx cap sync ios à nouveau.

L’app compile localement mais échoue en CI

Look for old CocoaPods assumptions: pod install, Pods/ caches, Podfile.lock clés de cache ou commandes de build pointant vers un .xcworkspace.

Signature ou entitlements modifiés

Comparez la cible Xcode migrée avec le projet d’origine. Restaurez l’identifiant de bundle, l’équipe, le profil de provisionnement, le fichier d’entitlements, les capacités et les paramètres d’extension.

Checklist de migration

Avant la migration :

Créer une branche.
Vérifier que l’application iOS actuelle compile.
Commiter l’état fonctionnel.
Inventory custom native files and signing settings.
Mettez à jour les dépendances natives qui ont déjà des releases plus récentes compatibles SPM.

Pendant la migration :

Exécutez npx cap spm-migration-assistant.
Ouvrez le projet avec npx cap open ios.
Ajoutez CapApp-SPM dans Xcode si nécessaire.
Ajoutez debug.xcconfig dans Xcode si nécessaire.
Résolvez les avertissements de package.
Exécutez npx cap sync ios.

Après la migration :

Compilez l'app depuis Xcode.
Testez les capacités natives sur un simulateur ou un appareil.
Supprimez les commandes CocoaPods du CI.
Supprimez les caches spécifiques à CocoaPods.
Vérifiez la signature de l’archive et de la release.

Utiliser les Capgo Skills pour la migration

Si vous utilisez des agents IA pour gérer la migration, commencez par skills Capgo open source plutôt qu’un prompt vide. Les skills les plus utiles pour ce travail sont :

capacitor-best-practices pour examiner la structure de l’app avant de la modifier ios/.
cocoapods-to-spm pour planifier la migration SPM et les étapes de suivi dans Xcode.
capacitor-ci-cd pour éliminer les hypothèses liées à CocoaPods des pipelines de build.
debugging-capacitor et ios-android-logs pour analyser les problèmes spécifiques aux appareils après la migration.

Utilisez-les avant de modifier le projet iOS afin que l’agent audite les fichiers natifs, la CI et la compatibilité des dépendances, au lieu de simplement exécuter la commande de migration.

Conclusion

Migrer une app Capacitor vers Swift Package Manager est principalement un changement de gestion des dépendances iOS. Le chemin le plus sûr consiste à partir d’une branche propre, à exécuter npx cap spm-migration-assistant, terminez les étapes manuelles dans Xcode, resynchronisez, puis supprimez CocoaPods de la CI uniquement une fois que l’application se compile.

Si votre projet iOS est fortement personnalisé, migrez sur place. S’il est proche du template Capacitor par défaut, recréer ios/ par npx cap add ios --packagemanager SPM peut être plus propre.