Migrando KMP de CocoaPods a Swift Package Manager

Image of the author

Germán Bustamante @germanbustamante

Flecha de migración de CocoaPods a Swift Package Manager

Migrando KMP de CocoaPods a Swift Package Manager

Este post está basado en la documentación oficial de Kotlin: Switching from CocoaPods to Swift Package Manager dependencies

Todo el crédito al equipo de JetBrains y Kotlin. JetBrains también ofrece una herramienta de migración asistida por IA en kmp-cocoapods-to-spm-migration. Recomiendo leer la documentación original para los detalles más actualizados.

🧠 Introducción: ¿Por Qué Migrar?

CocoaPods ha servido bien al ecosistema iOS, pero la tendencia es clara: Apple está invirtiendo en Swift Package Manager como solución nativa de gestión de dependencias, y la comunidad iOS más amplia lo está siguiendo. Para proyectos KMP, esto significa que el bloque Gradle cocoapods {} se está convirtiendo en una ruta de integración heredada.

Los costes prácticos de quedarse en CocoaPods:

La ruta de integración de SwiftPM para KMP ya es lo suficientemente madura como para que la migración esté bien definida y sea reversible. Esta guía la recorre paso a paso.

🗺️ Visión General de la Migración

La migración tiene tres fases, y de forma crítica, cada fase puede validarse antes de continuar:

  1. Actualizar el build script — añadir dependencias SwiftPM junto a CocoaPods (la coexistencia es intencional aquí)
  2. Reconfigurar Xcode — cambiar de la integración con CocoaPods a la integración directa
  3. Eliminar CocoaPods — limpiar el Podfile, la configuración de Gradle y los archivos generados

⚠️ No saltes al paso 3 antes de completar el paso 2. CocoaPods y la integración directa son mutuamente excluyentes en Xcode. Elimina CocoaPods solo después de que la reconfiguración de Xcode esté completa.

📝 Paso 1: Actualizar el Build Script

Requisito: Plugin de Gradle de Kotlin Multiplatform versión 2.3.20-titan-222 o posterior.

Añadir SwiftPM junto a CocoaPods

No elimines el bloque cocoapods {} todavía. Añade el bloque swiftPMDependencies junto a él:

// projectDir/sharedLogic/build.gradle.kts
kotlin {
    swiftPMDependencies {
        swiftPackage(
            url = url("https://github.com/firebase/firebase-ios-sdk.git"),
            version = from("12.5.0"),
            products = listOf(product("FirebaseAnalytics")),
        )
    }

    cocoapods {
        pod("FirebaseAnalytics") {
            version = "12.5.0"
        }
    }
}

Esto duplica temporalmente la dependencia. La coexistencia es intencional — permite actualizar las sentencias de import y verificar la compilación antes de tocar Xcode.

Actualizar las sentencias de import

// Antes
import cocoapods.FirebaseAnalytics.FIRAnalytics

// Después
import swiftPMImport.org.example.package.FIRAnalytics

El nuevo namespace sigue el patrón swiftPMImport.<gradle-group>.<nombre-modulo>. Ajusta org.example.package para que coincida con la configuración de group de tu módulo en build.gradle.kts.

Migrar la configuración del framework

CocoaPods configuraba el framework dentro del bloque cocoapods {}. Muévelo a la DSL estándar binaries.framework {}:

Antes:

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()
    cocoapods {
        framework {
            baseName = "Shared"
            isStatic = true
        }
    }
}

Después:

kotlin {
    listOf(
        iosArm64(),
        iosSimulatorArm64(),
        iosX64(),
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "Shared"
            isStatic = true
        }
    }
}

Compila y ejecuta tus tests de Kotlin en este punto para verificar que los cambios de import son correctos antes de tocar Xcode.

🔨 Paso 2: Reconfigurar Xcode

Este paso cambia el proyecto iOS de la integración con el plugin de Gradle de CocoaPods a la integración directa, que es necesaria para que SwiftPM funcione.

1. Abre el proyecto en Xcode

File | Open Project in Xcode

2. Lanza una build (fallará — es lo esperado)

Product | Build

La build fallará con un error. Esto es intencional: la salida del error contiene el comando de integración que necesitas.

3. Encuentra el comando en el reporte de build

Ve a View | Navigators | Report, filtra por Errors Only, y busca un comando similar a:

XCODEPROJ_PATH='/ruta/al/proyecto/iosApp/iosApp.xcodeproj' \
GRADLE_PROJECT_PATH=':sharedLogic' \
'/ruta/al/proyecto/gradlew' -p '/ruta/al/proyecto' \
':sharedLogic:integrateEmbedAndSign' \
':sharedLogic:integrateLinkagePackage'

4. Ejecuta ese comando

Ejecútalo desde el directorio iosApp. Este comando modifica tu archivo .xcodeproj para:

5. Resuelve las dependencias SwiftPM en IntelliJ IDEA

Tools | Swift Package Manager | Resolve Dependencies

Lanza la build del proyecto en Xcode de nuevo — ahora debería funcionar correctamente.

🧹 Paso 3: Eliminar CocoaPods

Una vez que la build de Xcode pase con la integración directa, CocoaPods puede eliminarse.

Opción A: Desintegración completa (todas las dependencias migradas)

Desde el directorio iosApp:

pod deintegrate

Esto elimina los archivos generados por CocoaPods del proyecto Xcode. Luego borra el directorio Pods/ y Podfile.lock.

Opción B: Eliminación parcial (quedan otros CocoaPods)

Si todavía tienes pods que no son KMP, edita el Podfile para eliminar solo la entrada del módulo KMP:

target 'iosApp' do
  # Elimina esta línea — sharedLogic es el nombre de tu módulo KMP
  # pod 'sharedLogic', :path => '../sharedLogic'

  # Mantén otros pods aquí
  pod 'SomeOtherPod'
end

Luego ejecuta:

pod install

Limpiar build.gradle.kts

Elimina el bloque cocoapods {} por completo:

// ELIMINA ESTE BLOQUE ENTERO
cocoapods {
    // ...
}

Si CocoaPods ya no se usa en ningún lugar del proyecto, elimina también las referencias al plugin en los bloques plugins {} tanto del build.gradle.kts raíz como del módulo compartido.

⚠️ Problemas Comunes y Consejos

💡 Conclusiones Clave

📚 Lectura Adicional