Comment migrer votre application Capacitor vers Swift Package Manager

Le gestionnaire de packages Swift est la direction par défaut pour les projets iOS Capacitor . Si votre application utilise toujours CocoaPods, vous pouvez migrer l'application elle-même vers SPM sans reconstruire votre projet JavaScript code ou votre flux de publication Android depuis zéro.

Cette guide est destiné aux équipes d'applications. Il explique comment migrer une application iOS Capacitor de CocoaPods vers SPM, ce que change l'assistant de migration, ce que vous devez encore vérifier dans Xcode et comment nettoyer CI après que l'application s'est construite.

Quels changements dans l'application

Une application iOS 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 iOS Capacitor basée sur SPM déplace la mise en relation des dépendances iOS dans le gestionnaire de packages Swift. Lors de la migration, Capacitor crée un package local nommé CapApp-SPM et l'utilise pour relier la cible d'application avec Capacitor et les dépendances natives installées.

La construction web fonctionne toujours de la même manière. Vous exécutez toujours une construction web, synchronisez Capacitor, ouvrez Xcode et archivez l'application. La principale différence est que CocoaPods ne possède plus le graphique de dépendance iOS.

Avant de migrer

Commencez d'une branche propre et assurez-vous que l'application actuelle se construit avant de modifier les gestionnaires de dépendances :

git status
npm run build
npx cap sync ios

Ensuite, commitez l'état de travail. La migration touche les fichiers de projet iOS générés, il est donc important d'avoir un point de rebond propre.

Ensuite, passez en revue ce que votre application a personnalisé sous ios/App/Les fichiers et les paramètres courants à conserver incluent :

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftsi présent
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistsi vous utilisez Firebase
personnalisé .xcconfig fichiers
paramètres de signature, identifiant de l'application, ID d'équipe, et profils de provisionnement
fichiers d'extension de l'application, 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 d'une application peut être bloquée par une dépendance native qui n'a pas de chemin compatible SPM. Mettez à jour ces packages avant de migrer lorsque possible.

Utilisez l'assistant de migration

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

npx cap spm-migration-assistant

Exécutez-le depuis la racine de votre projet Capacitor. L'assistant supprime l'intégration CocoaPods, crée le fichier local CapApp-SPM package, génère des références de package pour les dépendances natives installées et ajoute la configuration générée nécessaire au projet iOS.

Après cela, ouvrez le projet iOS :

npx cap open ios

Lisez l'output de l'assistant avant de fermer votre terminal. Si il vous demande de compléter des étapes manuelles Xcode, faites-les avant de synchroniser à nouveau.

Terminez les étapes Xcode

Vérifiez la configuration du projet et de la cible dans Xcode :

Confirm CapApp-SPM est ajouté comme dépendance de package local.
Confirmez que les liens de l'application cible se lient aux produits de package générés.
Ajoutez le généré debug.xcconfig Ajoutez le générateur à la configuration du projet si l'assistant vous le demande.
Résolvez les avertissements de package dans Xcode.
Effectuez une compilation de l'application une fois depuis Xcode.

Si Xcode ne peut pas résoudre les packages, utilisez Fichier > Packages > Réinitialiser les caches de package, puis résolvez les packages à nouveau.

Synchronisez et effectuez une nouvelle compilation

Après que Xcode soit configuré, revenez au terminal et synchronisez Capacitor :

npx cap sync ios

Then build from Xcode again. Do not treat the migration as done until a clean build works from Xcode, because release signing, entitlements, app extensions, and package resolution are validated there.

Si l'application utilise des notifications push, des domaines associés, des modes de fond, des groupes d'application, Firebase ou toute configuration native SDK, exécutez ces flux sur un simulateur ou un appareil après que la compilation réussisse.

Alternative : recréer iOS avec SPM

Si votre ios/ dossier est proche du modèle par défaut Capacitor, il peut être plus rapide de le recréer avec SPM au lieu de migrer en place.

Utilisez uniquement ce chemin après avoir commité ou sauvegardé chaque fichier natif et paramètre de signature dont vous avez besoin :

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

Récupérez ensuite vos fichiers et paramètres natifs spécifiques à l'application. Cette méthode vous donne un projet SPM propre, mais il est plus facile de perdre des modifications Xcode personnalisées si vous n'avez pas inventorié les modifications avant.

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

npx cap add ios

Vous pouvez toujours être explicite :

npx cap add ios --packagemanager SPM

Nettoyez les résidus de CocoaPods

Après que l'application SPM s'est construite, supprimez les hypothèses de CocoaPods des scripts locaux et de CI.

Supprimez les étapes comme :

pod install

Supprimez également les caches qui n'existaient que pour CocoaPods :

ios/App/Pods
ios/App/Podfile.lock
CocoaPods dépôts de spécifications
Clés de cache CI basées sur le fichier Podfile

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

npm ci
npm run build
npx cap sync ios

Si votre CI construit toujours App.xcworkspace, mettez à jour vers le chemin du projet ou du dossier de travail qui existe après la migration. N'entretenez pas les chemins CocoaPods obsolètes juste parce que l'ancien job les utilisait.

Troubleshooting

L'assistant vous avertit d'une dépendance incompatible

Update the dependency first and run the assistant again. If no SPM-compatible version exists, keep the app on CocoaPods until you replace that dependency or the maintainer adds SPM support.

Xcode ne peut pas résoudre les packages.

Xcode ne peut pas résoudre les packages CapApp-SPM est présent sous forme de package local, et exécutez npx cap sync ios again.

The app builds locally but CI fails

Recherchez les anciennes hypothèses CocoaPods : pod install, Pods/ cache, Podfile.lock clés de cache ou des commandes de construction pointant vers un projet supprimé .xcworkspace.

Signature ou droits modifiés

Comparez le cible Xcode migré à l'état initial du projet. Récupérez l'identifiant de l'application, l'équipe, le profil de provisioning, le fichier d'entitlements, les capacités et les paramètres d'extension.

Liste de vérification de migration

Avant la migration :

Créez une branche.
Confirmez que l'application iOS actuelle se compile.
Commitez l'état de travail.
Gérez vos fichiers natifs personnalisés et vos paramètres de signature.
Mettez à jour les dépendances natives qui disposent déjà de versions plus récentes compatibles avec 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 :

Construirez l'application à partir de Xcode.
Testez les capacités natives sur un simulateur ou un appareil.
Supprimer les commandes CocoaPods de CI.
Supprimer les caches CocoaPods uniquement.
Vérifiez la signature d'archive et de version.

Utiliser les Capgo compétences pour la migration.

Si vous utilisez des agents AI pour gérer la migration, commencez par les Capgo compétences au lieu d'une invitation vide. Les compétences les plus utiles pour ce travail sont :

capacitor-best-practices avant de procéder aux changements ios/.
cocoapods-to-spm planifier les étapes de migration de SPM et les suivis Xcode.
capacitor-ci-cd pour supprimer les hypothèses CocoaPods des pipelines de construction.
debugging-capacitor et ios-android-logs investiguer les problèmes liés uniquement aux appareils après la migration.

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

Conclusion

Migrer une application Capacitor vers le gestionnaire de packages Swift est principalement une modification de gestion de dépendances iOS. La voie la plus sûre est de commencer à partir d'une branch clean, exécuter npx cap spm-migration-assistantfinir les étapes manuelles Xcode, synchroniser à nouveau et supprimer CocoaPods de CI uniquement après que l'application s'exécute.

Si votre projet iOS est fortement personnalisé, migrez en place. Si il est proche du modèle de base Capacitor , la re création ios/ avec npx cap add ios --packagemanager SPM peut être plus propre.

Comment migrer votre application Capacitor vers le gestionnaire de packages Swift