Comment migrer une application Capacitor vers Swift Package Manager

Capacitor 8 crée de nouveaux projets iOS avec Swift Package Manager (SPM) par défaut. Les applications existantes qui utilisent encore CocoaPods peuvent également migrer, mais le chemin le plus sûr dépend du niveau de personnalisation native iOS de votre application.

Ce guide détaille les changements, les éléments à sauvegarder et les deux voies de migration pratiques : utiliser l’assistant de migration Capacitor ou recréer le projet iOS avec SPM.

Pourquoi migrer maintenant

CocoaPods évolue vers un trunk en lecture seule. Le plan actuel prévoit que le trunk CocoaPods cesse d’accepter de nouvelles podspecs le 2 décembre 2026. Les builds existants devraient continuer à fonctionner, mais les nouvelles releases et mises à jour de dépendances qui s’appuient sur le trunk ne seront plus publiées après le basculement.

SPM est aussi la direction dans laquelle Capacitor se dirige. Capacitor permet de choisir entre CocoaPods et SPM depuis Capacitor 6, et Capacitor 8 crée désormais des projets iOS SPM comme modèle par défaut.

Ce qui change dans un projet Capacitor SPM

Migrer de CocoaPods à SPM remplace la couche de dépendances iOS. L’app web, le projet Android et la plupart des commandes du workflow Capacitor restent identiques.

CapApp-SPM remplace le Podfile

Dans une application CocoaPods, les dépendances iOS sont gérées via ios/App/Podfile, Podfile.lock, Pods/, et le fichier généré .xcworkspace.

Dans une application SPM, Capacitor crée un package local nommé CapApp-SPM. Ce package devient le point central où Capacitor référence vos dépendances de plugins iOS natifs. Le Capacitor CLI se met à jour CapApp-SPM lorsque vous synchronisez les plugins. Considérez-le donc comme une sortie générée et évitez de le modifier à la main.

debug.xcconfig remplace la configuration de Pods

L’assistant de migration crée également un fichier généré debug.xcconfig. Ce fichier contient les paramètres de build que CocoaPods fournissait auparavant via ses fichiers xcconfig générés.

Après la migration, vous devrez peut-être ajouter debug.xcconfig à la configuration du projet Xcode si l’assistant vous le demande.

Chaque plugin doit prendre en charge SPM

Impossible de mélanger CocoaPods et SPM dans le même projet iOS Capacitor. Avant de migrer, vérifiez chaque Capacitor et plugin Cordova dans package.json.

Si un plugin ne prend pas encore en charge SPM, mettez-l’à jour, remplacez-l’ou migrez-le d’abord. Les plugins Swift simples peuvent souvent être convertis avec l’outil d’ capacitor-plugin-converter, mais les plugins avec des structures Objective-C et Swift plus complexes peuvent nécessiter un travail manuel.

Ce qu’il faut sauvegarder en premier

Commencez par une branche git propre et committez votre état actuel avant de toucher au projet iOS. Ensuite, listez les fichiers natifs dont votre application dépend.

Fichiers courants à conserver depuis ios/App/ incluent :

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, si votre application en possède un
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, si vous utilisez Firebase
Sur mesure .xcconfig fichiers
Paramètres de signature, identifiant de bundle, ID d’équipe et profil de provisionnement

Conservez également tous les fichiers Swift, Objective-C, framework, extension ou SDK que vous avez ajoutés en dehors du modèle standard Capacitor.

Option 1 : Utiliser l’assistant de migration Capacitor

Utilisez ce chemin si votre projet iOS contient des modifications natives personnalisées que vous ne souhaitez pas perdre.

Lancez l’assistant depuis la racine de votre projet Capacitor :

bunx cap spm-migration-assistant

L’assistant supprime l’infrastructure CocoaPods, crée le package local CapApp-SPM , génère les références de package à partir de vos plugins installés et crée les fichiers de configuration SPM générés.

Une fois terminé, ouvrez le projet :

bunx cap open ios

Puis suivez les étapes manuelles Xcode affichées par l’assistant. Dans la plupart des projets, cela signifie :

Ajoutez CapApp-SPM en tant que dépendance de package local.
Ajoutez le fichier debug.xcconfig généré à la configuration de l’application.
Résolvez les avertissements concernant les plugins qui n’ont pas pu être convertis en SPM.
Compilez l’app depuis Xcode une fois avant de mettre à jour la CI.

Une fois le projet Xcode compilé, resynchronisez :

bunx cap sync ios

Option 2 : Recréer le projet iOS avec SPM

Utilisez cette méthode si votre ios/ dossier est proche du modèle Capacitor par défaut et que vous pouvez restaurer en toute sécurité les fichiers personnalisés par la suite.

Assurez-vous d’abord que les fichiers listés dans la section de sauvegarde sont commités ou copiés dans un endroit sûr. Supprimez ensuite le projet iOS et recréez-l’avec SPM :

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

Restaurez les fichiers natifs dont votre application a besoin, puis ouvrez le projet :

bunx cap open ios

Cette approche est souvent plus propre qu'une migration sur place, car elle vous donne un template iOS Capacitor 8 tout neuf. En contrepartie, vous devez réappliquer soigneusement la signature, les entitlements, les fichiers Firebase, les modifications du code natif et tous les réglages Xcode personnalisés.

Nouvelles applications Capacitor

Pour une nouvelle application, Capacitor 8 utilise SPM par défaut lors de l'ajout d'iOS :

bunx cap add ios

Si vous préférez être explicite, vous pouvez toujours passer l'option du gestionnaire de paquets :

bunx cap add ios --packagemanager SPM

Mettre à jour la CI après la migration

Une fois que l'application compile en local, mettez à jour la CI/CD pour qu'elle ne repose plus sur CocoaPods.

Supprimez les étapes qui exécutent :

pod install

Supprimez également les caches pour :

ios/App/Pods
ios/App/Podfile.lock
Les dépôts de specs CocoaPods, si votre workflow ne les mettait en cache que pour cette application

Conservez vos étapes habituelles de build web et de sync Capacitor. Un job iOS typique doit installer les dépendances JavaScript, générer les assets web, synchroniser Capacitor, puis compiler avec Xcode :

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

Checklist de migration

Avant la migration :

Créez une nouvelle branche git.
Faites un commit de l’app en cours.
Vérifiez que chaque plugin installé prend en charge SPM.
Record custom iOS files and signing settings.
Confirmez que l’application compile avant la migration.

Pendant la migration :

Exécutez bunx cap spm-migration-assistant ou re-scaffolder ios/.
Ajoutez CapApp-SPM dans Xcode si nécessaire.
Ajoutez debug.xcconfig dans Xcode si nécessaire.
Restaurer les fichiers natifs spécifiques à l’app.
Exécutez bunx cap sync ios.

Après la migration :

Compiler et exécuter l’application dans Xcode.
Supprimer les fichiers CocoaPods résiduels.
Supprimer pod install de la CI.
Verify release signing still works.
Exécutez l’application sur au moins un simulateur et un appareil réel avant de déployer.

Troubleshooting

If Xcode cannot resolve packages, reset package caches from Xcode and run bunx cap sync ios à nouveau.

Si la migration échoue à cause d’un plugin, vérifiez s’il existe une release plus récente avec prise en charge de SPM. Pour les plugins que vous maintenez, migrez d’abord le package du plugin, puis revenez à la migration de l’application.

Si l’application compile localement mais que la CI échoue, vérifiez les hypothèses obsolètes liées à CocoaPods. Les causes courantes sont un .xcworkspace chemin de build forcé, une pod install commande obsolète, ou le cache Pods/ des builds précédents.

Conclusion

Migrer une application Capacitor vers Swift Package Manager consiste surtout à remplacer le câblage des dépendances iOS. CapApp-SPM reprend les références aux dépendances, debug.xcconfig remplace la configuration de build générée par CocoaPods, et le CI n’a plus besoin pod install.

Pour les projets iOS personnalisés, commencez par bunx cap spm-migration-assistant. Pour les projets proches du modèle par défaut, un re-scaffold SPM propre est souvent plus rapide et plus simple à comprendre.

Ressources

Continuer avec Comment migrer une application Capacitor vers Swift Package Manager

Si vous utilisez Comment migrer une application Capacitor vers Swift Package Manager pour planifier la migration et les opérations d'entreprise, connectez-l’à Capgo Entreprise pour le workflow produit dans Capgo Enterprise, Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise, Alternatives Capgo pour le workflow produit dans les alternatives Capgo, Conseil Capgo pour le workflow produit dans Capgo Consulting, et Support Premium Capgo pour le workflow produit dans Capgo Premium Support.