← The playbook

Kotlin Multiplatform

Kotlin Multiplatform in two established apps

Starting a new app on Kotlin Multiplatform is mostly a tooling exercise. Bringing it into two mature apps that already ship on their own is a different job. Each platform has years of code, its own release train and its own CI. And each has engineers who expect, fairly, that their build and their debugger won't get worse.

I designed and built a KMP framework for exactly that situation. It took the duplicated business and data-layer code out of both apps for everything that moved into it, and it left both native UI stacks alone. The moment I knew it had worked was when Android and iOS engineers started adding shared components to it without anyone asking.

Three repositoriesUI stays native, logic is shared
android-app
Compose UI + ViewModels
KeystoreTokenStoreImplements a shared interface
Gets the core as a git submodule, built together with the app.
ios-app
SwiftUI and UIKit
KeychainTokenStoreConforms to the same interface, in Swift
Gets the core as an XCFramework through SPM. No Gradle, no JDK.
both depend on ↓ and inject their own adapters into it
shared-kmp · its own repo, its own version number
Use casesBusiness rules, validation, state machines
InterfacesSecureTokenStore, Analytics, SessionRepository
Data, internalKtor client, retries, DTOs, caching
Exported as one umbrella framework, with SKIE so the types read naturally in Swift.
The host apps keep their screens and their hardware adapters. Rules, interfaces and networking live in the shared repository.

1. Why share at all

When two teams build the same spec separately, they drift. One app retries a 503 with backoff and the other gives up. One rounds currency differently. One logs an analytics property under a slightly different key and the funnel breaks downstream. Nobody did anything wrong. It's what happens when the same rule is written twice.

One Kotlin core for the domain and data layers fixes both problems at once. The duplicate implementation goes away, and the two apps behave the same because they're running the same code.

2. Share the core, keep the UI native

The fastest way to stall KMP in an established company is to push shared UI before you've earned trust lower down. Users notice a gesture or a transition that feels off. Platform engineers, on the other hand, rarely fight you over sharing JSON parsing, token refresh or a retry state machine.

Share in Kotlin (commonMain)Keep native (Compose & SwiftUI / UIKit)
API DTOs, request builders, and kotlinx.serializationScreens, layouts, view hierarchies, and navigation
HTTP client (Ktor), auth token refresh, and retry policiesGestures, haptics, transitions, and platform animations
Domain models, validation rules, and use casesPush notifications, home-screen widgets, and share extensions
Local caching, offline sync engines, and state machinesVoiceOver / TalkBack accessibility tuning
Analytics event schemas and telemetry payloadsHardware-backed Keystore / Keychain implementations

3. Interfaces over expect/actual

Early KMP codebases tend to reach for expect and actual for everything: secure storage, biometrics, logging. That ties the shared code to platform targets and makes it harder to test, because you can't easily swap an implementation in commonTest.

I keep nearly everything in commonMain, define a narrow interface for each platform capability, and let each app pass in its own implementation at startup.

KSecureTokenStore.ktshared/src/commonMain/kotlin/auth
interface SecureTokenStore {    suspend fun readToken(key: String): String?    suspend fun writeToken(key: String, value: String)    suspend fun clear(key: String)}sealed interface SessionResult {    data class Active(val userId: String, val expiresAtEpochMs: Long) : SessionResult    data object Expired : SessionResult    data class NetworkFailure(val retryable: Boolean) : SessionResult}class SessionRepository(    private val api: SessionApi,    private val tokenStore: SecureTokenStore,) {    suspend fun restoreSession(): SessionResult {        val rawToken = tokenStore.readToken("auth_session") ?: return SessionResult.Expired        return api.validateSession(rawToken)    }}

With that contract in place:

  • Android passes in an implementation backed by the Keystore and Tink.
  • iOS passes in a Swift class backed by Keychain Services, written and owned by iOS engineers.
  • Tests in commonTest use an in-memory fake and run on the JVM in milliseconds.

4. Its own repository

Where the shared code lives matters as much as how it's written. Put it inside the Android repository and iOS engineers become second-class users of an Android subproject. Merge everything into one giant repository and you're rewriting years of CI in one go.

We gave it a repository of its own, shared-kmp, with its own version numbers and its own pipeline.

What happens on a release tagone tag, two delivery paths
shared-kmp · release v1.8.0
✓ commonTest on the JVMevery pull request
✓ build iosArm64 + iosSimulatorArm64on tag
✓ bundle XCFramework + dSYMs, zip, SHA-256on tag
✓ publish Package.swift→ ios-app, via SPM
✓ cut the release branch→ android-app, via its submodule
iOS upgrades when iOS is readyXcode builds stay fast. Nothing to install.
Android upgrades when Android is readyMoves its submodule to the next release. Breakpoints work in shared code.
Neither app is forced onto the other's schedule, and iOS engineers never run Gradle.

Whether KMP survives across two teams comes down to the daily experience. If an iOS engineer has to install a JDK, babysit a Gradle daemon, or wait three minutes for Kotlin/Native every time they hit Cmd+R, they'll push back, and they should.

So each team keeps its own tools. For iOS, the shared repository's CI compiles the device and simulator targets on every tagged release, packs them into an XCFramework, archives the dSYMs, computes a checksum and publishes a Package.swift:

SPackage.swiftSwift
// swift-tools-version: 5.9// Published automatically by the shared KMP pipeline on every releaseimport PackageDescriptionlet package = Package(    name: "SharedCore",    platforms: [.iOS(.v16)],    products: [        .library(name: "SharedCore", targets: ["SharedCore"])    ],    targets: [        .binaryTarget(            name: "SharedCore",            url: "https://artifacts.example.com/kmp/1.8.0/SharedCore.xcframework.zip",            checksum: "<sha256 of the zip, written by CI>"        )    ])

For Android, the shared repository is plugged into the app as a git submodule and built with it as a Gradle composite build. The code is still maintained in its own repository; the app just pins the release it wants. When a feature spans the core and the Android UI, an engineer gets click-through navigation and breakpoints across both.

And because everything is versioned, each app adopts a new release on its own schedule. The two apps are never locked together.

5. Make Swift feel like Swift

Kotlin/Native reaches Swift through Objective-C headers, and a lot of type safety gets lost on the way. Without help, iOS engineers end up writing defensive boilerplate around your API.

Kotlin constructDefault Objective-C / Swift exportWith SKIE compiler plugin
sealed interface SessionResultPlain class hierarchy; Swift requires a default: branch in switchExhaustive Swift enum via onEnum(of:) with compiler-checked cases
Flow<T>Loses generic type arguments; requires manual callback collectorsNative Swift AsyncSequence usable directly in for await loops
suspend funCompletion-handler callbacks or unstructured async wrappersNative Swift async functions with structured task cancellation
Default parameter valuesStripped from Objective-C headers; callers must pass every argumentGenerates matching Swift function overloads with default arguments intact

Adding Touchlab's SKIE compiler plugin to the umbrella module removed almost all of that friction. iOS engineers consume shared state and sealed results with ordinary Swift concurrency:

SSessionGateView.swiftSwift
// iOS SwiftUI View consuming SharedCore with SKIE bindingsstruct SessionGateView: View {    let repository: SessionRepository    @State private var sessionState: SessionResult?    var body: some View {        Group {            switch onEnum(of: sessionState) {            case .active(let session):                HomeContainerView(userId: session.userId)            case .expired:                SignInView()            case .networkFailure(let failure):                RetryBannerView(canRetry: failure.retryable)            case nil:                ProgressView()            }        }        .task {            // Structured concurrency: cancelled automatically if the view disappears            self.sessionState = try? await repository.restoreSession()        }    }}

6. The rules I wouldn't bend

  • Ship one umbrella framework to iOS. Two separate KMP frameworks in one app each carry their own Kotlin/Native runtime. The app gets bigger, and types from one can't be passed to the other in Swift.
  • No uncaught Kotlin exception crosses into Swift. If one does, the iOS process dies on the spot. Catch at the repository boundary in commonMain and return a typed sealed error.
  • Budget for Kotlin/Native. Release frameworks for device and simulator take much longer than a JVM build. Run commonTest on the JVM for every pull request, build the full framework on merge, track its size every release, and keep the dSYMs so crash reports stay readable.
  • Own it together. PR templates, API reviews and architecture rules belong to both platforms. The best sign we got it right was iOS engineers opening pull requests in the Kotlin repository to add analytics and domain models themselves.