Cómo migrar tu app Capacitor a Swift Package Manager

Swift Package Manager es la dirección por defecto para proyectos iOS de Capacitor. Si tu app aún usa CocoaPods, puedes migrar la propia app a SPM sin reconstruir tu code de JavaScript, tu proyecto Android ni tu flujo de release desde cero.

Esta guía es para equipos de apps. Explica cómo migrar una app iOS de Capacitor de CocoaPods a SPM, qué cambia el asistente de migración, qué debes revisar aún en Xcode y cómo limpiar la CI después de que la app compila.

Qué cambia en la app

Una app de Capacitor basada en CocoaPods depende de archivos como:

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

Una app de Capacitor basada en SPM mueve la configuración de dependencias iOS a Swift Package Manager. Durante la migración, Capacitor crea un paquete local llamado CapApp-SPM y lo usa para conectar el target de la app con Capacitor y las dependencias nativas instaladas.

El build web sigue funcionando igual. Sigues ejecutando un build web, sincronizando Capacitor, abriendo Xcode y archivando la app. La principal diferencia es que CocoaPods ya no gestiona el grafo de dependencias iOS.

Antes de migrar

Empieza desde una rama limpia y asegúrate de que la app actual compila antes de cambiar los gestores de dependencias:

git status
npm run build
npx cap sync ios

Luego, commitea el estado funcional. La migración toca archivos del proyecto iOS generados, por lo que tener un punto de rollback limpio es importante.

A continuación, revisa qué ha personalizado tu app bajo ios/App/. Los archivos y ajustes comunes que conviene conservar incluyen:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, si están presentes
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, si usas Firebase
personalizados .xcconfig archivos
ajustes de firma, bundle identifier, team ID y perfiles de aprovisionamiento
extensiones de app, archivos Swift nativos, archivos Objective-C o frameworks embebidos

Revisa también tus dependencias de Capacitor y Cordova instaladas. Una migración a SPM a nivel de app puede bloquearse si una dependencia nativa no tiene una ruta compatible con SPM. Actualiza esos paquetes antes de migrar cuando sea posible.

Usa el asistente de migración

Para la mayoría de las apps existentes, empieza con el asistente de migración oficial de Capacitor:

npx cap spm-migration-assistant

Ejecútalo desde la raíz de tu proyecto de Capacitor. El asistente elimina la integración de CocoaPods, crea el paquete local CapApp-SPM , genera referencias de paquete para las dependencias nativas instaladas y añade la configuración generada necesaria para el proyecto de iOS.

Cuando termine, abre el proyecto de iOS:

npx cap open ios

Lee la salida del asistente antes de cerrar la terminal. Si te pide completar pasos manuales en Xcode, hazlos antes de sincronizar de nuevo.

Completa los pasos de Xcode

En Xcode, verifica la configuración del proyecto y el target de la app:

Confirmar CapApp-SPM se añade como una dependencia de paquete local.
Confirma que el target de la app enlaza los productos del paquete generado.
Añade el generado debug.xcconfig a la configuración del proyecto si el asistente lo solicita.
Resuelve los warnings de paquetes en Xcode.
Haz un build de la app desde Xcode.

Si Xcode no puede resolver los paquetes, usa Archivo > Paquetes > Restablecer caché de paquetes, y luego vuelve a resolver los paquetes.

Sincroniza y haz el build de nuevo

Una vez configurado Xcode, vuelve a la terminal y sincroniza Capacitor:

npx cap sync ios

Luego haz el build desde Xcode otra vez. No des la migración por terminada hasta que un build limpio funcione desde Xcode, ya que ahí se validan la firma de release, los entitlements, las app extensions y la resolución de paquetes.

Si la app usa push notifications, associated domains, background modes, app groups, Firebase o cualquier configuración nativa de SDK, ejecuta esos flujos en un simulador o dispositivo tras completar el build.

Alternativa: recrear iOS con SPM

Si tu ios/ Si la carpeta es similar a la plantilla Capacitor por defecto, puede ser más rápido recrearla con SPM en lugar de migrarla in situ.

Usa esta ruta solo después de hacer commit o respaldar cada archivo nativo y cada ajuste de firma que necesites:

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

Luego restaura tus archivos y ajustes nativos específicos de la app. Esta ruta te da un proyecto SPM limpio, pero es más fácil perder cambios personalizados de Xcode si antes no hiciste un inventario de ellos.

Para apps nuevas de Capacitor, Capacitor 8 crea proyectos iOS con SPM por defecto:

npx cap add ios

Aun así, puedes ser explícito:

npx cap add ios --packagemanager SPM

Limpiar restos de CocoaPods

Tras compilar la app con SPM, elimina las dependencias de CocoaPods de tus scripts locales y de la CI.

Elimina pasos como:

pod install

También elimina las cachés que solo existían para CocoaPods:

ios/App/Pods
ios/App/Podfile.lock
Repositorios de especificaciones de CocoaPods
Claves de caché de CI basadas en el Podfile

Un flujo básico de CI tras la migración debe instalar las dependencias de JavaScript, compilar la app web, sincronizar Capacitor y compilar con Xcode:

npm ci
npm run build
npx cap sync ios

Si tu CI aún compila App.xcworkspace, actualízalo a la ruta del proyecto o workspace que existe tras la migración. No mantengas rutas de CocoaPods obsoletas solo porque el trabajo anterior las usaba.

Solución de problemas

El asistente advierte sobre una dependencia incompatible

Actualiza primero la dependencia y vuelve a ejecutar el asistente. Si no existe una versión compatible con SPM, mantén la app en CocoaPods hasta que reemplaces esa dependencia o el mantenedor añada soporte para SPM.

Xcode no puede resolver los paquetes

Restablece las cachés de paquetes en Xcode, verifica que CapApp-SPM esté presente como un paquete local y ejecuta npx cap sync ios de nuevo.

La app compila localmente pero falla en CI

Busca suposiciones antiguas de CocoaPods: pod install, Pods/ cachés, Podfile.lock claves de caché o comandos de build que apunten a un .xcworkspace.

Cambio en la firma o los entitlements

Compara el target de Xcode migrado con el proyecto anterior. Restaura el identificador del bundle, el equipo, el perfil de aprovisionamiento, el archivo de entitlements, las capacidades y la configuración de extensiones.

Checklist de migración

Antes de la migración:

Crea una rama.
Confirma que la app de iOS actual compila.
Commitea el estado funcional.
Inventario de archivos nativos personalizados y configuraciones de firma.
Actualiza las dependencias nativas que ya tienen versiones más recientes compatibles con SPM.

Durante la migración:

Ejecuta npx cap spm-migration-assistant.
Abre el proyecto con npx cap open ios.
Añadir CapApp-SPM en Xcode si es necesario.
Añadir debug.xcconfig en Xcode si es necesario.
Resuelve las advertencias de paquetes.
Ejecuta npx cap sync ios.

Tras la migración:

Compila la app desde Xcode.
Prueba las capacidades nativas en un simulador o dispositivo.
Elimina los comandos de CocoaPods de tu CI.
Elimina los caches exclusivos de CocoaPods.
Verifica el archive y la firma de release.

Usa Capgo Skills para la migración

Si usas agentes de IA para la migración, empieza desde Capgo Skills abiertas en lugar de un prompt vacío. Los skills más útiles para este trabajo son:

capacitor-best-practices para revisar la estructura de la app antes de cambiar ios/.
cocoapods-to-spm para planificar la migración a SPM y los pasos de seguimiento en Xcode.
capacitor-ci-cd para eliminar los supuestos de CocoaPods de los pipelines de build.
debugging-capacitor y ios-android-logs para investigar problemas específicos del dispositivo tras la migración.

Úsalos antes de modificar el proyecto de iOS para que el agente audite archivos nativos, CI y compatibilidad de dependencias, en lugar de solo ejecutar el comando de migración.

Conclusión

Migrar una app de Capacitor a Swift Package Manager es principalmente un cambio en la gestión de dependencias de iOS. La ruta más segura es empezar desde una rama limpia y ejecutar npx cap spm-migration-assistant, completa los pasos manuales de Xcode, sincroniza de nuevo y elimina CocoaPods de CI solo cuando la app compile.

Si tu proyecto de iOS está muy personalizado, migra in situ. Si es similar a la plantilla predeterminada de Capacitor, recrea ios/ con npx cap add ios --packagemanager SPM puede ser más limpio.