Cómo Migrar su Aplicación Capacitor a Swift Package Manager

El Gestor de Paquetes Swift es la dirección por defecto para los proyectos de Capacitor iOS. Si su aplicación todavía utiliza CocoaPods, puede migrar la aplicación en sí a SPM sin tener que reconstruir su proyecto de JavaScript code, proyecto Android o flujo de lanzamiento desde cero.

Esta guía está destinada a equipos de aplicaciones. Explica cómo migrar una aplicación de Capacitor iOS desde CocoaPods a SPM, qué cambia el asistente de migración, qué aún necesita verificar en Xcode y cómo limpiar el CI después de que la aplicación se construye.

¿Qué cambia en la aplicación

Una aplicación de Capacitor basada en CocoaPods depende de archivos como:

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

Una aplicación de Capacitor basada en SPM mueve la configuración de dependencias de iOS al Gestor de Paquetes Swift. Durante la migración, Capacitor crea un paquete local llamado CapApp-SPM y utiliza para conectar la aplicación objetivo con Capacitor y dependencias nativas instaladas.

La compilación web sigue funcionando de la misma manera. Todavía ejecuta una compilación web, sincroniza Capacitor, abre Xcode y archiva la aplicación. La principal diferencia es que CocoaPods ya no es dueño de la gráfica de dependencias iOS.

Antes de migrar

Comienza desde una rama limpia y asegúrate de que la aplicación actual se compile antes de cambiar los administradores de dependencias:

git status
npm run build
npx cap sync ios

Luego, haz un commit del estado de trabajo. La migración afecta archivos de proyecto iOS generados, por lo que tener un punto de rollback limpio es importante.

A continuación, revisa qué ha personalizado su aplicación bajo ios/App/Archivos y configuraciones comunes para preservar incluyen:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, si está presente
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, si utiliza Firebase
personalizado .xcconfig archivos
configuración de firmas, identificador de paquete, ID de equipo y perfiles de provisión
extensiones de la aplicación, archivos Swift nativos, archivos de Objective-C o frameworks incorporados

También compruebe sus dependencias de Capacitor y Cordova instaladas. Una migración de SPM de nivel de aplicación puede bloquearse por una dependencia nativa que no tiene un camino compatible con SPM. Actualice esos paquetes antes de migrar cuando sea posible.

Utilice el asistente de migración

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

npx cap spm-migration-assistant

Ejecute desde la raíz de tu proyecto Capacitor. El asistente elimina la integración de CocoaPods, crea el archivo local CapApp-SPM paquete, genera referencias de paquete para dependencias nativas instaladas, y agrega la configuración generada necesaria por el proyecto de iOS.

Después de que termine, abre el proyecto de iOS:

npx cap open ios

Lee el resultado del asistente antes de cerrar su terminal. Si te pide que completes pasos manuales de Xcode, hazlo antes de sincronizar de nuevo.

Finalice los pasos de Xcode

En Xcode, verifica la configuración del proyecto y destino de la aplicación:

Confirm CapApp-SPM se agrega como una dependencia de paquete local.
Confirm the app target links the generated package products.
Agregar los generados debug.xcconfig a la configuración del proyecto si el asistente lo solicita.
Resolver cualquier advertencia de paquete en Xcode.
Construya la aplicación una vez desde Xcode.

Si Xcode no puede resolver paquetes, utilice Archivo > Paquetes > Reiniciar Cachés de Paquetesy resuelva los paquetes de nuevo.

Sincronice y construya de nuevo

Después de que Xcode esté configurado, regrese al terminal y sincronice Capacitor:

npx cap sync ios

Luego construya desde Xcode de nuevo. No trate la migración como hecha hasta que una construcción limpia funcione desde Xcode, porque la firma de liberación, las autorizaciones, las extensiones de la aplicación, la resolución de paquetes se validan allí.

Si la aplicación utiliza notificaciones de empuje, dominios asociados, modos de fondo, grupos de la aplicación, Firebase o cualquier configuración nativa SDK, ejecute esas flujos en un simulador o dispositivo después de que la construcción tenga éxito.

Alternativa: recrea iOS con SPM

Si su ios/ carpeta está cerca del modelo predeterminado Capacitor, puede ser más rápido recrearla con SPM en lugar de migrar en su lugar.

Sólo utilice este camino después de haber cometido o respaldado todos los archivos nativos y ajustes de firma que necesite:

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

Luego restaure sus archivos y ajustes nativos específicos de la aplicación. Este camino le da un proyecto SPM limpio, pero es más fácil perder cambios personalizados de Xcode si no los inventarió primero.

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

npx cap add ios

Todavía puede ser explícito:

npx cap add ios --packagemanager SPM

Elimine residuos de CocoaPods

Después de que SPM construye la aplicación, elimine las suposiciones de CocoaPods de los scripts locales y CI.

Elimine pasos como:

pod install

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

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

Un flujo CI básico después de la migración debería instalar dependencias de JavaScript, compilar la aplicación web, sincronizar Capacitor y compilar con Xcode:

npm ci
npm run build
npx cap sync ios

Si tu CI sigue construyendo App.xcworkspace, actualiza a la ruta del proyecto o espacio de trabajo que existe después de la migración. No mantengas rutas de CocoaPods obsoletas solo porque la antigua tarea las utilizaba.

Solución de problemas

La asistente advierte sobre una dependencia incompatible

Actualiza la dependencia primero y ejecuta la asistente de nuevo. Si no existe una versión compatible con SPM, mantén la aplicación en CocoaPods hasta que reemplaces esa dependencia o el mantenedor agregue soporte para SPM.

Xcode no puede resolver paquetes

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

La aplicación se compila localmente pero CI falla

Busque suposiciones de CocoaPods antiguas: pod install, Pods/ cachés, Podfile.lock claves de caché o comandos de compilación que apuntan a un archivo eliminado .xcworkspace.

Cambios en la firma o permisos

Compare el objetivo de Xcode migrado con el proyecto previo a la migración. Restaure el identificador de paquete, equipo, perfil de provisión, archivo de permisos, capacidades y ajustes de extensión.

Lista de verificación de migración

Antes de la migración:

Cree una rama.
Confirme que la aplicación iOS actual se compila.
Comita el estado de trabajo.
Inventarie archivos nativos personalizados y ajustes de firma.
Actualice dependencias nativas que ya tienen versiones más recientes compatibles con SPM.

Durante la migración:

Ejecutar npx cap spm-migration-assistant.
Abra el proyecto con npx cap open ios.
Agregar CapApp-SPM en Xcode si es necesario.
Agregar debug.xcconfig en Xcode si es necesario.
Resolver advertencias de paquetes.
Ejecutar npx cap sync ios.

Después de la migración:

Construya la aplicación desde Xcode.
Pruebe las capacidades nativas en un simulador o dispositivo.
Elimine comandos de CocoaPods de CI.
Elimine cachés solo de CocoaPods.
Verifique la firma de archivo y de lanzamiento.

Utilice Capgo habilidades para la migración.

Si utiliza agentes de IA para manejar la migración, comience desde Capgo habilidades en lugar de una solicitud en blanco. Las habilidades más útiles para este trabajo son:

capacitor-best-practices revisar la estructura de la aplicación antes de realizar cambios ios/.
cocoapods-to-spm planificar los pasos de migración de SPM y Xcode.
capacitor-ci-cd eliminar suposiciones de CocoaPods de las líneas de construcción.
debugging-capacitor y ios-android-logs investigar problemas solo de dispositivo después de la migración.

Utilícelos antes de cambiar el proyecto iOS para que el agente audite archivos nativos, CI y compatibilidad de dependencias en lugar de ejecutar solo el comando de migración.

Conclusión

Migrar una aplicación Capacitor a Swift Package Manager es principalmente un cambio en la gestión de dependencias de iOS. El camino más seguro es comenzar desde una rama limpia, ejecutar npx cap spm-migration-assistantFinalice los pasos manuales de Xcode, sincronice nuevamente y elimine CocoaPods de CI solo después de que se compile la aplicación.

Si su proyecto de iOS está muy personalizado, migre en lugar. Si está cerca del template de Capacitor por defecto, recrear ios/ con npx cap add ios --packagemanager SPM puede ser más limpio.

Cómo migrar su aplicación de Capacitor a Gestor de Paquetes de Swift