Exportando Módulos KMP como Swift Packages para iOS

Image of the author

Germán Bustamante @germanbustamante

Logo de Kotlin Multiplatform con icono de Swift Package Manager

Exportando Módulos KMP como Swift Packages para iOS

Este post está basado en la documentación oficial de Kotlin: Swift Package Export Setup

Todo el crédito al equipo de JetBrains y Kotlin. Recomiendo leer la documentación original junto a este post.

🧠 Introducción: Reduciendo la Fricción de Adopción en iOS

Uno de los desafíos recurrentes de Kotlin Multiplatform es la historia de integración en el lado iOS. Los desarrolladores iOS viven en Xcode, piensan en Swift y quieren añadir dependencias como siempre lo han hecho — a través de Swift Package Manager.

Si tu módulo KMP no puede consumirse como un Swift package, los desarrolladores iOS tienen que adoptar un flujo de trabajo nuevo solo para usar tu código compartido. Esa fricción es real y ralentiza la adopción. La buena noticia es que KMP tiene soporte de primera clase para distribuirse como un XCFramework envuelto en un Swift package, y la configuración es más directa de lo que parece.

En mi experiencia, la inversión en esta configuración se amortiza rápido: una vez que tu módulo KMP es un Swift package correcto, el equipo iOS puede consumirlo exactamente como cualquier otra dependencia — sin necesitar conocimientos de Gradle.

📦 Lo Que Necesitas para Distribuir

Un Swift package respaldado por un XCFramework binario requiere dos artefactos:

Eligiendo la Estructura de Repositorio

Hay tres opciones para ubicar tu Package.swift, y la elección importa más de lo que parece:

🔧 Configurando el Build de Gradle

En tu shared/build.gradle.kts, configura el XCFramework:

import org.jetbrains.kotlin.gradle.plugin.mpp.apple.XCFramework

kotlin {
    val xcframeworkName = "Shared"
    val xcf = XCFramework(xcframeworkName)

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64(),
    ).forEach {
        it.binaries.framework {
            baseName = xcframeworkName
            binaryOption("bundleId", "org.example.${xcframeworkName}")
            xcf.add(this)
            isStatic = true
        }
    }
}

Algunas cosas que vale la pena destacar:

Luego ejecuta la tarea de ensamblado:

./gradlew :shared:assembleSharedXCFramework

El resultado se genera en shared/build/XCFrameworks/release/Shared.xcframework.

Para proyectos de Compose Multiplatform el módulo suele ser composeApp:

./gradlew :composeApp:assembleSharedXCFramework

📤 Empaquetado y Distribución

Paso 1: Comprimir y calcular el checksum

# Comprimir el XCFramework
zip -r Shared.xcframework.zip Shared.xcframework

# Calcular el checksum (requerido para Package.swift)
swift package compute-checksum Shared.xcframework.zip

Paso 2: Subir a GitHub Releases

  1. Ve a tu repositorio → Releases → Create a new release
  2. Crea un tag de versión semántica (ej: 1.0.0)
  3. Adjunta el ZIP en el campo Attach binaries
  4. Publica el release
  5. Clic derecho en el ZIP bajo Assets → Copiar dirección del enlace

Verifica que el enlace sea públicamente accesible antes de continuar:

curl -I <tu-enlace-de-descarga>
# Debe devolver HTTP 200 o un redirect al asset

Paso 3: Crear Package.swift

// swift-tools-version:5.3
import PackageDescription

let package = Package(
    name: "Shared",
    platforms: [
        .iOS(.v14),
    ],
    products: [
        .library(name: "Shared", targets: ["Shared"])
    ],
    targets: [
        .binaryTarget(
            name: "Shared",
            url: "<enlace al ZIP del XCFramework subido>",
            checksum: "<checksum calculado para el ZIP>"
        )
    ]
)

Paso 4: Validar y publicar

# Validar el manifiesto
swift package reset && swift package show-dependencies --format json

# Publicar Package.swift en tu repositorio dedicado
git add Package.swift
git commit -m "Release 1.0.0"
git tag 1.0.0
git push origin main --tags

🏗️ Exportando Múltiples Módulos

Si tu proyecto tiene módulos separados network y database que quieres exponer como un único Swift package, puedes crear un módulo umbrella.

Configura el umbrella together/build.gradle.kts

kotlin {
    val frameworkName = "together"
    val xcf = XCFramework(frameworkName)

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            export(projects.network)
            export(projects.database)
            baseName = frameworkName
            xcf.add(this)
        }
    }

    sourceSets {
        commonMain.dependencies {
            api(projects.network)
            api(projects.database)
        }
    }
}

Cada módulo incluido debe declarar targets iOS

// network/build.gradle.kts
kotlin {
    android { }
    iosX64()
    iosArm64()
    iosSimulatorArm64()
}

Workaround: crea un archivo Kotlin vacío

Gradle requiere al menos un archivo fuente para ensamblar el framework. Crea:

together/src/commonMain/kotlin/Together.kt

Déjalo vacío o añade un comentario — su contenido no importa.

Luego ensambla:

./gradlew :together:assembleTogetherReleaseXCFramework

Los consumidores Swift pueden importar ambos módulos con un único import together.

✅ Verificando la Integración

En Xcode, ve a File | Add Package Dependencies, pega la URL de tu repositorio con Package.swift, y añade el package.

Prueba el import con una vista SwiftUI mínima:

import SwiftUI
import Shared

struct ContentView: View {
    var body: some View {
        VStack {
            Text("Platform: \(Shared.Platform_iosKt.getPlatform().name)")
        }
        .padding()
    }
}

Si el preview compila y muestra el nombre de la plataforma, la integración funciona correctamente.

💡 Conclusiones Clave

📚 Lectura Adicional