Cómo migrar una app de Capacitor a Swift Package Manager

Capacitor 8 crea nuevos proyectos de iOS con Swift Package Manager (SPM) de forma predeterminada. Las aplicaciones existentes que aún usan CocoaPods también pueden migrar, pero la ruta más segura depende de cuánto personalización nativa de iOS tenga tu app.

Esta guía explica qué cambia, qué hacer copia de seguridad y las dos rutas prácticas de migración: usar el asistente de migración de Capacitor o re-crear el proyecto de iOS con SPM.

Por qué migrar ahora

CocoaPods se está moviendo hacia un trunk de solo lectura. El plan actual es que el trunk de CocoaPods deje de aceptar nuevos podspecs el 2 de diciembre de 2026. Las compilaciones existentes deberían seguir funcionando, pero las nuevas versiones y actualizaciones de dependencias que dependan del trunk no se publicarán allí después del cambio.

SPM también es la dirección hacia la que se mueve Capacitor. Capacitor ha permitido elegir entre CocoaPods o SPM desde Capacitor 6, y Capacitor 8 ahora crea proyectos de iOS SPM como plantilla predeterminada.

Qué cambia en un proyecto SPM de Capacitor

Migrar de CocoaPods a SPM reemplaza la capa de dependencias de iOS. La app web, el proyecto de Android y la mayoría de los comandos de flujo de trabajo de Capacitor permanecen igual.

CapApp-SPM reemplaza el Podfile

En una app de CocoaPods, las dependencias de iOS se conectan a través de ios/App/Podfile, Podfile.lock, Pods/, y el generado .xcworkspace.

En una app de SPM, Capacitor crea un paquete local llamado CapApp-SPM. Este paquete se convierte en el lugar central donde Capacitor referencia tus dependencias de plugins nativos de iOS. El Capacitor CLI se actualiza CapApp-SPM cuando sincronizas plugins, así que trátalo como salida generada y evita editarlo manualmente.

debug.xcconfig reemplaza la configuración de Pods

El asistente de migración también crea un debug.xcconfig. Este archivo contiene las configuraciones de build que CocoaPods solía proporcionar a través de sus archivos xcconfig generados.

Tras la migración, es posible que tengas que añadir debug.xcconfig a la configuración del proyecto de Xcode si el asistente te lo indica.

Cada plugin debe ser compatible con SPM

No puedes mezclar CocoaPods y SPM en el mismo proyecto iOS de Capacitor. Antes de migrar, verifica cada Capacitor y plugin de Cordova en package.json.

Si un plugin aún no es compatible con SPM, actualízalo, reemplázalo o migra el plugin primero. Los plugins Swift simples a menudo se pueden convertir con el de Ionic capacitor-plugin-converter, pero los plugins con estructuras más complejas de Objective-C y Swift pueden requerir trabajo manual.

Qué hacer de copia de seguridad primero

Comienza desde una rama git limpia y haz commit de tu estado actual antes de tocar el proyecto de iOS. Luego, lista los archivos nativos de los que depende tu app.

Archivos comunes que conservar de ios/App/ incluyen:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, si tu app tiene uno
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, si usas Firebase
Personalizado .xcconfig archivos
Ajustes de firma, bundle identifier, team ID y ajustes de provisioning profile

También conserva cualquier archivo nativo de Swift, Objective-C, framework, extensión o SDK que hayas añadido fuera de la plantilla estándar de Capacitor.

Opción 1: Usa el asistente de migración de Capacitor

Usa esta opción si tu proyecto de iOS tiene modificaciones nativas personalizadas que no quieres perder.

Ejecuta el asistente desde la raíz de tu proyecto Capacitor:

bunx cap spm-migration-assistant

El asistente elimina la infraestructura de CocoaPods, crea el paquete CapApp-SPM package, genera referencias de paquetes a partir de tus plugins instalados y crea los archivos de configuración SPM generados.

Cuando termine, abre el proyecto:

bunx cap open ios

Luego sigue los pasos manuales de Xcode que imprime el asistente. En la mayoría de los proyectos, esto significa:

Añadir CapApp-SPM como dependencia de paquete local.
Add the generated debug.xcconfig a la configuración de la app.
Resuelve cualquier advertencia sobre plugins que no se pudieron convertir a SPM.
Compila la app desde Xcode una vez antes de actualizar la CI.

After the Xcode project builds, sync again:

bunx cap sync ios

Opción 2: Re-crea el proyecto de iOS con SPM

Usa esta ruta cuando tu ios/ directorio esté cerca de la plantilla predeterminada de Capacitor y puedas restaurar los archivos personalizados con seguridad después.

Primero, asegúrate de que los archivos listados en la sección de copia de seguridad estén comprometidos o copiados en un lugar seguro. Luego, elimina y recrea el proyecto de iOS con SPM:

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

Restaura los archivos nativos que tu app necesita y abre el proyecto:

bunx cap open ios

Esta ruta suele ser más limpia que una migración in situ porque te da una plantilla de Capacitor 8 iOS nueva. El contratiempo es que debes reaplicar cuidadosamente la firma, los permisos, los archivos de Firebase, los cambios en el código nativo y cualquier configuración personalizada de Xcode.

Nuevas apps de Capacitor

Para una app nueva, Capacitor 8 usa SPM por defecto al añadir iOS:

bunx cap add ios

Si necesitas ser explícito, aún puedes pasar la opción de gestor de paquetes:

bunx cap add ios --packagemanager SPM

Actualiza CI después de la migración

Una vez que la app se compile localmente, actualiza CI/CD para que ya no asuma CocoaPods.

Elimina los pasos que ejecutan:

pod install

También elimina las cachés de:

ios/App/Pods
ios/App/Podfile.lock
Repositorios de specs de CocoaPods, si tu workflow solo los cacheaba para esta app

Mantén tu build web habitual y los pasos de sincronización de Capacitor. Un trabajo de iOS típico debería instalar las dependencias de JavaScript, compilar los assets web, sincronizar Capacitor y luego compilar con Xcode:

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

Checklist de migración

Antes de la migración:

Crea una nueva rama en git.
Haz commit de la app actual.
Verifica que cada plugin instalado soporte SPM.
Registra archivos iOS personalizados y configuraciones de firma.
Confirma que la app compile antes de migrar.

Durante la migración:

Ejecuta bunx cap spm-migration-assistant o regenera el scaffold ios/.
Añadir CapApp-SPM en Xcode si es necesario.
Añadir debug.xcconfig en Xcode si es necesario.
Restaura los archivos nativos de la app.
Ejecuta bunx cap sync ios.

Tras la migración:

Haz el build y ejecuta la app en Xcode.
Elimina los archivos residuales de CocoaPods.
Eliminar pod install desde CI.
Verifica que el signing de release siga funcionando.
Ejecuta la app en al menos un simulador y un dispositivo real antes de publicar.

Solución de problemas

Si Xcode no puede resolver los paquetes, reinicia el caché de paquetes desde Xcode y ejecuta bunx cap sync ios de nuevo.

Si la migración falla por un plugin, verifica si existe una versión más reciente con soporte para SPM. Para los plugins que mantengas, migra primero el paquete del plugin y luego vuelve a la migración de la app.

Cuando la app se compila localmente pero falla en CI, revisa suposiciones antiguas de CocoaPods. Las causas habituales son una .xcworkspace un comando obsoleto o caché pod install de builds anteriores. Pods/ de builds anteriores.

Conclusión

Migrar una app de Capacitor a Swift Package Manager consiste principalmente en reemplazar la configuración de dependencias de iOS. CapApp-SPM asume las referencias de dependencias, debug.xcconfig reemplaza la configuración de build generada por CocoaPods, y la CI ya no necesita pod install.

Para proyectos de iOS personalizados, empieza con bunx cap spm-migration-assistant. Para proyectos cercanos a la plantilla predeterminada, un re-scaffold limpio con SPM suele ser más rápido y fácil de razonar.

Recursos

Continuar desde Cómo migrar una app Capacitor a Swift Package Manager

Si estás usando Cómo migrar una app de Capacitor a Swift Package Manager para planificar la migración y las operaciones enterprise, conéctalo con Capgo Enterprise para el flujo de trabajo del producto en Capgo Enterprise, Alternativas a plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Enterprise, Alternativas a Capgo para el flujo de trabajo del producto en Capgo Alternatives, Consultoría de Capgo para el flujo de trabajo del producto en Capgo Consulting, y Soporte Premium de Capgo para el flujo de trabajo del producto en Capgo Premium Support.