How to Seamlessly Integrate Kotlin Multiplatform into iOS Projects

Overview

Kotlin Multiplatform (KMP) enables writing shared business logic once and running it on multiple platforms. For iOS, the shared Kotlin code is compiled with Kotlin/Native into a standard iOS framework that can be consumed by Xcode like any native library.

Integrating KMP Modules into iOS

Local Integration (source‑level collaboration)

When the iOS project and the KMP shared module live in the same repository, developers can choose direct integration or CocoaPods‑based integration.

Direct Integration : Add a Run Script phase in Xcode that invokes the Gradle task to compile the Kotlin module and produce the latest framework on each build. This approach requires no third‑party package manager.

CocoaPods Integration : Apply the kotlin-native-cocoapods Gradle plugin to generate a podspec. Then reference the pod in the iOS Podfile using :path => '../shared'.

# Podfile
target 'ios-app' do
  use_frameworks!
  platform :ios, '14.1'

  # Reference the local KMP module
  pod 'shared', :path => '../shared'
end

Remote Integration (module as an independent dependency)

When the shared module is maintained by a different team or needs versioned distribution, it can be published as a binary framework.

Swift Package Manager (SPM) : Package the compiled framework as an XCFramework and create a Package.swift manifest that points to the binary URL and checksum.

// Package.swift
import PackageDescription
let package = Package(
    name: "Shared",
    platforms: [.iOS(.v14)],
    products: [.library(name: "Shared", targets: ["Shared"])],
    targets: [.binaryTarget(name: "Shared", url: "https://your-server.com/releases/shared.xcframework.zip", checksum: "your-checksum-here")]
)

CocoaPods Distribution : Publish the generated XCFramework to a private or public podspec repository using the same plugin, allowing teams that already rely on CocoaPods to consume the module.

Swift/Objective‑C Interoperability

Kotlin/Native generates an Objective‑C header (e.g., Shared.h) that acts as a bridge. Types are mapped as follows: class → class /

@interface

interface

→ protocol /

@protocol

String

→ String /

NSString

List<T>

→ Array<T> /

NSArray<T>

Map<K,V>

→ Dictionary<K,V> /

NSDictionary<K,V>

suspend fun

→ async / completionHandler Best practices include using @ObjCName to give Kotlin APIs Swift‑friendly names, @HiddenFromObjC to hide unwanted symbols, and writing KDoc comments so they appear as Objective‑C documentation in Xcode.

Build and Packaging

In build.gradle.kts, define iOS targets ( iosX64, iosArm64, iosSimulatorArm64) and configure an XCFramework binary.

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

    val xcf = XCFramework()
    listOf(iosX64(), iosArm64(), iosSimulatorArm64()).forEach {
        it.binaries.framework {
            baseName = "shared"
            xcf.add(this)
        }
    }
}

Run the Gradle task assembleSharedReleaseXCFramework to produce the framework in build/XCFrameworks.

Debugging and Testing

Debugging : Xcode can debug Kotlin code directly; the compiler generates .dSYM files for symbolication.

Testing : Write platform‑agnostic tests in the commonTest source set. These tests can be executed on iOS simulators to verify shared logic.

When to Use KMP

Ideal Scenarios : Share data, domain, and presentation‑layer code (networking, database, business rules, ViewModel/Presenter) across iOS and Android.

UI Layer : KMP does not handle UI; native SwiftUI/UIKit or Compose Multiplatform should be used separately.

Gradual Adoption : Start with a small module (e.g., networking) and expand the shared codebase incrementally.

Conclusion

Kotlin Multiplatform provides a pragmatic way for iOS developers to reuse business logic by compiling it into a standard iOS framework that works with Xcode, Swift, SPM, and CocoaPods. Although some learning is required for interop and build configuration, the resulting productivity gains and cross‑platform consistency make KMP a compelling choice for modern mobile development.