Comment migrer une application Capacitor vers Swift Package Manager

Capacitor 8 crée de nouveaux projets iOS avec le gestionnaire de packages Swift (SPM) par défaut. Les applications existantes qui utilisent encore CocoaPods peuvent migrer également, mais la voie la plus sûre dépend de la quantité de personnalisation native iOS que votre application a.

Cette guide passe en revue les changements, ce qui doit être sauvegardé, et les deux chemins de migration pratiques : utiliser l'assistant de migration Capacitor ou restructurer le projet iOS avec SPM.

Pourquoi migrer maintenant

CocoaPods se tourne vers un tronc en lecture seule. Le plan actuel est de faire cesser l'acceptation de nouvelles spécifications de pod le 2 décembre 2026. Les builds existants devraient continuer à fonctionner, mais les nouvelles publications et les mises à jour de dépendances qui dépendent du tronc ne seront plus publiées après le basculement.

SPM est également la direction que Capacitor est en train de suivre. Capacitor a soutenu le choix entre CocoaPods et SPM depuis Capacitor 6, et Capacitor 8 crée désormais des projets iOS SPM par défaut.

Quels changements dans un projet Capacitor SPM

Migrer de CocoaPods à SPM remplace la couche de dépendances iOS. L'application web, le projet Android et la plupart des commandes de flux de travail Capacitor restent les mêmes.

CapApp-SPM remplace le fichier Podfile

Dans une application CocoaPods, les dépendances iOS sont liées par 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 lieu central où Capacitor référence vos dépendances de plugin iOS natives. Le Capacitor CLI met à jour CapApp-SPM lorsque vous synchronisez les plugins, traitez-le donc comme un résultat généré et évitez de le modifier à la main.

debug.xcconfig remplace la configuration Pods

L’assistant de migration crée également un fichier généré debug.xcconfig. Ce fichier contient les paramètres de construction que CocoaPods fournissait précédemment à travers 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 recommande.

Tout plugin doit supporter SPM

Vous ne pouvez pas 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 supporte pas encore SPM, mettez-l’à jour, le remplacez ou migrez le plugin en premier. Les plugins Swift simples peuvent souvent être convertis avec Ionic’s capacitor-plugin-converter, mais les plugins avec des layouts Objective-C et Swift plus complexes peuvent nécessiter du travail manuel.

Quels fichiers sauvegarder en premier

Commencez d'une branche Git propre et commitez votre état actuel avant de toucher le projet iOS. Ensuite, listez les fichiers natifs dont votre application a besoin.

Fichiers courants à conserver de ios/App/ include :

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftSi votre application en a un
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistSi vous utilisez Firebase
Custom .xcconfig Fichiers
Paramètres de signature, identifiant de bundle, ID d'équipe et paramètres de profil de provisionnement

Conservez également tout fichier Swift natif, Objective-C, framework, extension ou SDK que vous avez ajouté en dehors du modèle standard Capacitor.

Option 1 : Utilisez l'assistant de migration Capacitor

Utilisez ce chemin lorsque votre projet iOS comporte des éditions natives personnalisées que vous ne souhaitez pas perdre.

Exécutez l'assistant depuis la racine de votre projet Capacitor :

bunx cap spm-migration-assistant

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

Lorsqu'il est terminé, ouvrez le projet :

bunx cap open ios

Suivez ensuite les étapes manuelles de Xcode indiquées par l'assistant. Dans la plupart des projets, cela signifie :

Add CapApp-SPM comme une dépendance de package local.
à la configuration de l'application. debug.xcconfig à la configuration de l'application.
Résolvez tout avertissement concernant les plugins qui ne pouvaient pas être convertis en SPM.
Build the app from Xcode once before updating CI.

Après la construction du projet Xcode, synchronisez à nouveau :

bunx cap sync ios

Option 2 : Re-scaffolder le projet iOS avec SPM

Utilisez ce chemin lorsque votre ios/ répertoire est proche du modèle par défaut Capacitor et vous pouvez restaurer en toute sécurité les fichiers personnalisés par la suite.

First, make sure the files listed in the backup section are committed or copied somewhere safe. Then remove and recreate the iOS project with 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

This path is often cleaner than an in-place migration because it gives you a fresh Capacitor 8 iOS template. The tradeoff is that you must carefully reapply signing, entitlements, Firebase files, native source changes, and any custom Xcode settings.

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

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

bunx cap add ios

Si vous devez être explicite, vous pouvez toujours passer l'option de gestionnaire de package :

bunx cap add ios --packagemanager SPM

Mettre à jour CI après la migration

Une fois l'application construite localement, mettez à jour CI/CD afin qu'il ne suppose plus CocoaPods.

Supprimer les étapes qui exécutent :

pod install

Supprimer également les caches pour :

ios/App/Pods
ios/App/Podfile.lock
Les dépôts de spécifications CocoaPods, si votre workflow les a stockés uniquement pour cette application

Conservez vos étapes de construction régulières web et de synchronisation Capacitor. Une tâche iOS typique doit installer les dépendances JavaScript, construire les actifs web, synchroniser Capacitor, puis construire avec Xcode :

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

Guide de migration

Avant la migration :

Créez une nouvelle branche Git.
Commitez l'application en cours de travail.
Vérifiez que chaque plugin installé prend en charge SPM.
Record custom iOS files and signing settings.
Confirmez que l'application se construit avant la migration.

Durant la migration :

Exécuter bunx cap spm-migration-assistant re-scaffold ios/.
Add CapApp-SPM dans Xcode si nécessaire.
Add debug.xcconfig dans Xcode si nécessaire.
Restore app-specific native files.
Exécuter bunx cap sync ios.

si nécessaire, dans Xcode.

Restaurer les fichiers natifs spécifiques à l'application.
Supprimer les fichiers CocoaPods restants.
Supprimer pod install du CI.
Verify release signing still works.
Lancer l'application sur au moins un simulateur et un appareil réel avant de la livrer.

Troubleshooting

Si Xcode ne peut pas résoudre les packages, réinitialisez les caches de packages depuis Xcode et exécutez bunx cap sync ios again.

If the migration fails because of a plugin, check whether the plugin has a newer release with SPM support. For plugins you maintain, migrate the plugin package first and then return to the app migration.

When the app builds locally but CI fails, check for old CocoaPods assumptions. Common causes are a forced .xcworkspace chemin de build, un obsolète pod install commande, ou mise en cache Pods/ de précédentes constructions.

Conclusion

Migrer une application Capacitor vers le gestionnaire de packages Swift consiste principalement à remplacer la configuration des dépendances iOS. CapApp-SPM prend en charge les références de dépendances. debug.xcconfig remplace la configuration de build CocoaPods générée, et le CI n'a plus besoin pod install.

Pour les projets iOS personnalisés, commencez par bunx cap spm-migration-assistantPour les projets proches du modèle par défaut, une restructuration SPM propre est souvent plus rapide et plus facile à comprendre.

Resources

Continuez de la migration de votre application Capacitor vers le gestionnaire de packages Swift

Si vous utilisez La migration de votre application Capacitor vers le gestionnaire de packages Swift Pour planifier la migration et les opérations d'entreprise, connectez-l’à Capgo Entreprise pour le flux de travail du produit dans Capgo Enterprise, Alternatives d'extension Ionic Enterprise pour le flux de travail du produit dans les alternatives du plugin Enterprise Ionic Capgo Alternatives pour le flux de travail du produit dans Capgo Alternatives, Consultation Capgo pour le flux de travail du produit dans Capgo Consulting, et Capgo Support Premium pour le flux de travail du produit dans Capgo Support Premium.

Comment migrer une application Capacitor vers le gestionnaire de packages Swift