Importing Swift Packages into KMP: An Experimental Guide

Image of the author

Germán Bustamante @germanbustamante

Swift Package Manager dependencies flowing into Kotlin Multiplatform

Importing Swift Packages into KMP: An Experimental Guide

This post is based on the official Kotlin documentation: Adding Swift packages as dependencies to KMP modules

Full credit to the JetBrains and Kotlin team. I recommend reading the original docs alongside this post.

⚠️ This feature is experimental. It requires a development build of Kotlin (2.3.20-titan-222) and is not intended for production use yet. Share feedback in the #kmp-swift-package-manager Slack channel.

🧠 Introduction: The Missing Piece

Before this feature, using an iOS-specific SDK from shared KMP code was painful. Your options were:

None of these feel natural if you are coming from the Swift/Xcode side of the world. Swift Package Manager is how iOS developers manage dependencies, and it has been for years. The swiftPMDependencies DSL brings that familiarity to KMP: declare your Swift package dependencies in Gradle the same way you would in a Package.swift, and use the imported APIs directly in your iosMain Kotlin code.

This is a meaningful step toward making KMP feel native on both sides of the stack — and it changes the calculus for teams evaluating KMP adoption.

⚠️ Experimental Status and Limitations

Before going further, the constraints:

With that said, if you are prototyping, exploring KMP adoption, or contributing to the ecosystem — this is genuinely exciting.

🔧 Setup

1. Configure settings.gradle.kts

Add the JetBrains development Maven repository so Gradle can find the experimental plugin:

dependencyResolutionManagement {
    repositories {
        maven("https://packages.jetbrains.team/maven/p/kt/dev")
        mavenCentral()
    }
}

pluginManagement {
    repositories {
        maven("https://packages.jetbrains.team/maven/p/kt/dev")
        mavenCentral()
        gradlePluginPortal()
    }
}

2. Pin the Kotlin version

In your version catalog (libs.versions.toml):

[versions]
kotlin = "2.3.20-titan-222"

[plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }

If you need to force the plugin version in the root build.gradle.kts:

buildscript {
    dependencies.constraints {
        "classpath"("org.jetbrains.kotlin:kotlin-gradle-plugin:2.3.20-titan-222")
    }
}

3. IDE Plugin Setup (optional)

If your team uses the Kotlin Multiplatform IDE plugin, point it to the iOS project path:

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

    swiftPMDependencies {
        xcodeProjectPathForKmpIJPlugin.set(
            layout.projectDirectory.file("../iosApp/iosApp.xcodeproj")
        )
    }
}

📦 Adding SwiftPM Dependencies

Declare your dependencies inside the swiftPMDependencies block:

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

    swiftPMDependencies {
        swiftPackage(
            url = url("https://github.com/firebase/firebase-ios-sdk.git"),
            version = from("12.5.0"),
            products = listOf(product("FirebaseAnalytics")),
        )

        swiftPackage(
            url = url("https://github.com/apple/swift-protobuf.git"),
            version = exact("1.32.0"),
            products = listOf(),
        )
    }
}

Version Specification Options

The version parameter supports several strategies — pick the one that fits your stability requirements:

version = from("1.0")          // 1.0 or newer (Gradle 'require')
version = exact("2.0")         // exactly 2.0 (Gradle 'strict')
version = branch("main")       // track a branch (unstable — use with care)
version = revision("e74b07...")// pin to a specific commit

Clang Module Discovery

By default, the plugin automatically discovers all Clang modules in the specified products. If you need fine-grained control — for example, when the Clang module name differs from the product name — disable auto-discovery:

swiftPMDependencies {
    discoverClangModulesImplicitly = false

    swiftPackage(
        url = url("https://github.com/firebase/firebase-ios-sdk.git"),
        version = from("12.5.0"),
        products = listOf(
            product("FirebaseAnalytics"),
            product("FirebaseFirestore")
        ),
        importedClangModules = listOf(
            "FirebaseAnalytics",
            "FirebaseFirestoreInternal"  // note: differs from product name
        ),
    )
}

🌍 Platform Constraints

If your project targets multiple Apple platforms and a dependency only supports iOS, restrict it:

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()
    macosArm64()

    swiftPMDependencies {
        swiftPackage(
            url = url("https://github.com/googlemaps/ios-maps-sdk.git"),
            version = exact("10.3.0"),
            products = listOf(
                product(
                    "GoogleMaps",
                    platforms = setOf(iOS())
                )
            )
        )
    }
}

Without the platforms constraint, Gradle would try to link Google Maps against macOS targets and fail.

You can also set minimum deployment targets per platform:

swiftPMDependencies {
    iosMinimumDeploymentTarget.set("16.0")
    macosMinimumDeploymentTarget.set("13.0")
}

📱 Using Imported APIs in Kotlin

Imported APIs are available under the namespace:

swiftPMImport.<gradle-group>.<module-name>.<APIName>

If your module’s build.gradle.kts declares group = "org.example" and the module is named shared:

// shared/src/iosMain/kotlin/Analytics.kt
import swiftPMImport.org.example.shared.FIRAnalytics
import swiftPMImport.org.example.shared.FIRApp

fun initFirebase() {
    FIRApp.configure()
}

fun logEvent(name: String) {
    FIRAnalytics.logEventWithName(name, parameters: null)
}

The Kotlin compiler handles the Objective-C interop layer — you call the Firebase APIs as if they were regular Kotlin functions.

📂 Local Swift Packages

You can also import Swift packages from the local filesystem, which is useful for packages your team maintains internally or for prototyping:

// /path/to/LocalPackage/Package.swift
let package = Package(
    name: "LocalPackage",
    platforms: [.iOS("15.0")],
    products: [
        .library(name: "LocalPackage", targets: ["LocalPackage"]),
    ],
    targets: [
        .target(name: "LocalPackage")
    ]
)
// shared/build.gradle.kts
swiftPMDependencies {
    localSwiftPackage(
        directory = project.layout.projectDirectory.dir("/path/to/LocalPackage/"),
        products = listOf("LocalPackage")
    )
}

⚡ Dynamic vs Static Frameworks

If you’re using isStatic = false (dynamic framework), you may encounter:

These happen because Swift packages can bundle native code that conflicts with your dynamic framework’s linkage. The fix is straightforward:

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

My recommendation: start with isStatic = true unless you have a concrete reason for dynamic linkage. You can always revisit this later.

💡 Key Takeaways

📚 Further Reading