Adopting KMP in Existing Android and iOS Apps

Under AGP 9, the com.android.application and com.android.library plugins can no longer be applied in the same module as the Kotlin Multiplatform plugin, so the Android app has to live in its own module regardless. Doing it first, as a pure refactoring, removes the biggest source of confusion later. The full procedure is in The Android Target and AGP 9. Existing Android project layout concepts are in Android: Project Structure and Gradle.

TrailMate starts with a single app module. Create sharedLogic next to it. The shared module uses the KMP Android-library plugin, declares the targets it must support, and starts with an empty commonMain.

Add include(":sharedLogic") and include(":androidApp") to settings.gradle.kts. See Kotlin docs — Multiplatform project configuration.

See Kotlin docs — Add dependencies to your project. The target hierarchy, source sets and the kotlin { android { } } block are explained in Project Structure and Source Sets and Gradle Configuration and Compatibility.

The androidApp module declares implementation(project(":sharedLogic")); see Android Developers — Set up the Android Gradle library plugin for KMP.

Shared code can only use libraries that have a multiplatform artifact. Instead of moving everything and then fighting hundreds of unresolved imports, replace one library at a time inside the Android app first, where the compiler and your existing tests still protect you.

The Android-specific versions of these libraries are covered in Android: Networking with Retrofit, OkHttp and Ktor, Android: Room and Paging and Android: Dependency Injection with Hilt and Koin; the multiplatform side is in Networking with the Ktor Client, Local Storage and Dependency Injection.

With the libraries swapped, moving code is mostly git mv plus fixing imports. Move in this order: models and DTOs, data sources, repositories, use cases, then ViewModels. Each move compiles on its own, because the Android app already depends on sharedLogic. The ViewModel is where most surprises live: the androidx.lifecycle.ViewModel class has a multiplatform artifact, but anything that touched Context, SavedStateHandle constructors or viewModelScope extension imports must change.

See Kotlin docs — Common ViewModel. Patterns for exposing state to both platforms are in Architecture, Shared ViewModels and State, and the original Android ViewModel is explained in Android: ViewModel, Lifecycle and Coroutines. Android-only needs inside the shared code (a Context, a FusedLocationProviderClient) are handled with interfaces or with expect/actual; see expect/actual and Platform APIs.

Once the logic lives in sharedLogic, adding iOS is the next section. Sharing UI is a separate, later decision: Jetpack Compose screens can move to sharedUI one at a time because Compose Multiplatform preserves the Jetpack Compose API, so the Android app keeps compiling after every move. See Compose Multiplatform Fundamentals and Kotlin docs — Compose Multiplatform and Jetpack Compose. Teams that keep SwiftUI skip step 5 and lose nothing; both paths are in iOS Integration Options. Views-based screens must first move to Compose, see Android: Migrating from Views to Compose.

In a monorepo, the Android app uses project(":sharedLogic") and the Xcode project runs embedAndSignAppleFrameworkForXcode, so everything is built from source and debugging across Kotlin and Swift is straightforward.

In a separate repository, the shared module publishes two artifacts. Android consumes the Maven publication; iOS consumes an XCFramework through Swift Package Manager. The Gradle target hierarchy in build.gradle.kts already registers XCFramework("TrailMateShared"), so assembleTrailMateSharedReleaseXCFramework produces the zip. The Package.swift in the shared repository points to the released zip with a checksum:

See Kotlin docs — Set up an XCFramework for Swift Package Manager distribution. The checksum is a placeholder, produced with swift package compute-checksum TrailMateShared.xcframework.zip; never commit a made-up value. The Android side uses an ordinary dependency:

See Kotlin docs — Set up multiplatform library publication. The whole publishing flow, including Maven Central and a release workflow that attaches the zip and checksum, is in Publishing Multiplatform Libraries and CI/CD for KMP with GitHub Actions. Importing a Kotlin framework through SwiftPM from source (rather than the binary) is Alpha; the binary XCFramework route above is the established one. Apple-side packaging is covered in Apple: Swift Packages and Modularization.

A change to a shared API is really two changes: the Kotlin signature and the Swift surface the iOS app sees. A reviewer who only reads Kotlin will approve a perfectly idiomatic Kotlin API that is awkward or unusable from Swift. Make the Swift view of the change part of review:

Checking the API surface for accidental breakage is covered by the binary-compatibility tooling described in Publishing Multiplatform Libraries, and test strategy in Testing Multiplatform Code.

Practical tactics that work: pair an iOS engineer with an Android engineer on the first feature, let the iOS engineers define the Swift-facing API, and write down exit criteria so that stopping a small pilot stays cheap. Record the decision as recommended in Backend Architecture: Decisions and Migrations.