Why Kotlin Multiplatform

Suppose your school-fees app is a success on Android, and the bursar's office asks for an iPhone version, and the head teacher wants a desktop version for the school computer. The traditional answer is to write the app again in Swift for iOS, with its own bugs, its own business rules and its own team. When the fee rule changes, you change it twice, and the two apps slowly drift apart.

Kotlin Multiplatform (KMP) offers another answer: write the parts that are the same once, in Kotlin, and compile them for every platform, while keeping each platform's own UI and system APIs where that matters. This lesson opens the Kotlin Multiplatform programme at https://developer.android.com/courses/pathways/kotlin-multiplatform (Why you should adopt Kotlin Multiplatform and Get started with Kotlin Multiplatform). The programme links to the JetBrains documentation at https://www.jetbrains.com/help/kotlin-multiplatform-dev/ and to Google's guidance at https://developer.android.com/kotlin/multiplatform.

By the end you will be able to:

• Explain what KMP is and how it differs from "write once, run anywhere" frameworks.
• Describe how Kotlin compiles to each target.
• Decide what to share and what to keep native.
• Use expect/actual and interfaces to reach platform APIs.
• Compare KMP, Compose Multiplatform, Flutter and React Native fairly.
• Make an honest adopt / do not adopt decision for a project.

Big idea: KMP is about sharing the right code, not all the code. Share the logic that is identical, and let each platform keep what is special.

Honesty note: the KMP tooling changes quickly (Gradle plugins, the Android target, which libraries support which targets). This lesson explains stable ideas and shows code in the style of current documentation, but check the official pages for the current setup before starting a real project. The ten-style list of reasons below is my own summary of the common arguments; JetBrains publishes its own list at https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-reasons-to-try.html, and you should read it too.

• Kotlin classes, interfaces and functions (lessons 6 to 14).
• Coroutines and Flow (lesson 33).
• App architecture and layers (lessons 60 to 65), because the layered design decides what is easy to share.
• Gradle Kotlin DSL and version catalogs (lessons 3 and 34).
• Room and Retrofit (lessons 29 and 34), which you will meet again in KMP form.

One language, many targets

A target is a platform your code is compiled for. Kotlin can compile to several:

You write common Kotlin that uses only the Kotlin standard library and multiplatform libraries. The Kotlin compiler produces the correct output for each target. On iOS your shared code becomes a framework that Swift code imports, like any other iOS library.

Where the code lives

A KMP module is split into source sets:

shared/
  src/
    commonMain/kotlin/       code for ALL targets
    commonTest/kotlin/       tests for common code
    androidMain/kotlin/      Android-only code
    iosMain/kotlin/          iOS-only code

Common code cannot call Android or iOS APIs directly, because it must compile everywhere. When it needs a platform feature, you use expect/actual or an interface (below).

What KMP is not

• It is not a UI toolkit. By default, your Android app still uses Compose and your iOS app still uses SwiftUI. (Compose Multiplatform is a separate JetBrains framework that can share UI as well; see the comparison below.)
• It is not "all or nothing". You can share a single module, a single class, or the whole data layer, in an existing app.
• It does not hide the platform. You still build and ship an Android app and an iOS app, each with its own entry point.

The usual arguments, in my own words:

Limits to be honest about:

• iOS builds need a Mac with Xcode, always. You can learn and ship the Android half on any computer, but running the iOS app needs Apple's tools.
• Not every library is multiplatform. Some Android libraries have no iOS version, so you find alternatives or use expect/actual.
• Build setup is more complex than a single-platform app, and tooling changes between releases.
• The team needs to cooperate. iOS developers must be willing to use a Kotlin-built framework, and Kotlin/Swift interop has some rough edges (for example with generics and sealed classes).
• It is not always worth it. An app with little shared logic, or a team already happy with two native codebases, may gain little.

Business logic that needs nothing special

Our FeeTracker rule from lesson 63 uses only Kotlin, so it can move to commonMain unchanged:

// shared/src/commonMain/kotlin/com/example/fees/FeeSummary.kt
package com.example.fees
data class FeeSummary(val paid: Long, val balance: Long) {
 val isOwing: Boolean get() = balance > 0
}
class CalculateFeeSummary(private val termFee: Long = 450_000) {
 operator fun invoke(payments: List<Long>): FeeSummary {
 val paid = payments.sum()
 return FeeSummary(paid = paid, balance = termFee - paid)
 }
}

Why this works: no Android imports, no java.* classes (those do not exist on iOS), just Kotlin's standard library. This is the strongest argument for the plain Kotlin domain layer in lesson 63: it is already shareable.

A test in commonTest runs on every target:

// shared/src/commonTest/kotlin/com/example/fees/FeeSummaryTest.kt
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
class FeeSummaryTest {
 @Test
 fun balance_is_term_fee_minus_payments() {
 val summary = CalculateFeeSummary(termFee = 100)(listOf(30, 20))
 assertEquals(50, summary.balance)
 assertTrue(summary.isOwing)
 }
}

Notice kotlin.test, not JUnit: JUnit is a JVM library, so common tests use the multiplatform kotlin.test API. The same test runs on the JVM (Android host tests) and, on a Mac, on the iOS simulator.

What you cannot use in common code

Most of your lessons already used the multiplatform-friendly choices (coroutines, Flow, kotlinx.serialization), so your code is closer to KMP than you might think.

Sometimes common code needs something only the platform knows, such as the device name or the current time zone. Declare what you need in common code, and supply how on each platform.

// commonMain/Platform.kt
expect fun platformName(): String
fun greeting(): String = "Hello from ${platformName()}!"

// androidMain/Platform.android.kt
import android.os.Build
actual fun platformName(): String = "Android ${Build.VERSION.SDK_INT}"

// iosMain/Platform.ios.kt
import platform.UIKit.UIDevice
actual fun platformName(): String =
 UIDevice.currentDevice.systemName() + " " + UIDevice.currentDevice.systemVersion

• expect is a promise: "every target will provide this".
• actual is the fulfilment in a platform source set. If a target lacks an actual, the build fails, so you cannot forget one.
• greeting() lives in common code and works everywhere, calling the right actual at run time.
• On iOS, Kotlin has access to Apple's frameworks through the platform.* packages (here UIKit).

expect/actual also works for classes:

// commonMain
expect class Clock() {
 fun nowMillis(): Long
}

// androidMain
actual class Clock actual constructor() {
 actual fun nowMillis(): Long = System.currentTimeMillis()
}

Often better: an interface

expect/actual is compile-time and rigid. For most application code, a plain interface in common code, with implementations supplied by each platform app, is more flexible and easier to test:

// commonMain
interface TokenStorage {
 suspend fun read(): String?
 suspend fun write(token: String)
}
class LoginUseCase(private val storage: TokenStorage, private val api: AuthApi) {
 suspend operator fun invoke(user: String, password: String): Result<Unit> = runCatching {
 val token = api.login(user, password)
 storage.write(token)
 }
}

// androidMain
class AndroidTokenStorage(private val context: Context) : TokenStorage {
 override suspend fun read(): String? = /* EncryptedSharedPreferences or DataStore */ null
 override suspend fun write(token: String) { /* ... */ }
}

// iosApp (Swift): Keychain implementation of the same Kotlin interface
class KeychainTokenStorage: TokenStorage {
 func read() async throws -> String? { /* Keychain lookup */ return nil }
 func write(token: String) async throws { /* Keychain save */ }
}

The shared LoginUseCase depends on the interface, not the platform. This is the dependency inversion idea from lessons 60 and 65 doing real work. A rule of thumb from experience: use expect/actual for tiny, stateless platform facts (a platform name, a UUID generator), and interfaces plus injection for services (storage, notifications, biometrics).

Understanding the pipeline removes much of the mystery.

commonMain  ─┐
             ├─► compiled for Android ──► .class bytecode ─► your Android app
androidMain ─┘

commonMain  ─┐
             ├─► compiled for iOS ─────► native code ───────► shared.framework ─► Xcode app
iosMain     ─┘

1. For each target, the Kotlin compiler combines commonMain with that target's own source set.
2. For Android and JVM, the output is bytecode, exactly as in any Android module.
3. For iOS, Kotlin/Native compiles to machine code and packages it as a framework (and, with Swift Package Manager export, an XCFramework: lesson 69). Swift sees Kotlin classes as Objective-C-style classes with a generated header.
4. Dependencies must also have a version for each target. A multiplatform library publishes a common variant plus per-target artifacts, and Gradle picks the right ones automatically.

The Gradle setup is a short kotlin { } block. You will study it line by line in lesson 67; here is a preview so that it does not look strange later:

// shared/build.gradle.kts (preview; see lesson 67 for the current Android target setup)
plugins {
 alias(libs.plugins.kotlin.multiplatform)
 alias(libs.plugins.android.kotlin.multiplatform.library)
}
kotlin {
 android {
 namespace = "com.example.fees.shared"
 compileSdk = 36
 minSdk = 24
 }
 iosArm64()
 iosSimulatorArm64()
 sourceSets {
 commonMain.dependencies {
 implementation(libs.kotlinx.coroutines.core)
 }
 commonTest.dependencies {
 implementation(kotlin("test"))
 }
 }
}

A practical way to choose, layer by layer, using the architecture from lessons 60 to 65:

Start small. The recommended adoption path is: (1) share a pure-Kotlin domain module, (2) share networking and models, (3) share the database, (4) consider shared state holders and, only if you want to, shared UI.

What a good first candidate looks like

• It has clear inputs and outputs (a function from payments to a summary).
• It has no UI and no platform calls.
• It is already tested and stable.
• Both teams care about consistency (money calculations, validation, date rules).

Points of fairness:

• Compose Multiplatform is built on Kotlin Multiplatform and is developed by JetBrains. Its iOS support has been reaching stable status in recent releases; check the current status page before relying on any particular platform.
• None of these is "the best". A team of Android developers with an existing native app usually finds KMP the smoothest path; a startup with no native code and a small team may prefer a single-UI framework.
• Whatever you choose, measure with a small prototype before committing, as lesson 57 taught for performance.

Create a short decision record for a project. A good one answers:

Project:        FeeTracker (Android today; iOS and desktop requested)
Shared code:    domain rules, networking models, repositories, database
Native code:    UI, notifications, camera for receipts
Team:           3 Android developers, 1 iOS developer
Risks:          iOS developer unfamiliar with Kotlin framework; one Android library has no iOS version
Mitigation:     pair on the first shared module; replace the library with a multiplatform one
First step:     move CalculateFeeSummary and models to :shared, tests green on both platforms
Decision:       Adopt incrementally. Review after the first release.

Writing it down forces honest answers and makes the review easy later.

Mistake #1: Importing java.* or android.* in common code. Fix: use multiplatform libraries or interfaces.

Mistake #2: Trying to share everything on day one. Fix: start with the domain layer.

Mistake #3: Using JUnit in commonTest. Fix: use kotlin.test.

Mistake #4: Overusing expect/actual. Fix: prefer interfaces for services.

Mistake #5: Forgetting the iOS side needs a Mac. Fix: plan hardware and CI early.

Mistake #6: Choosing libraries without checking target support. Fix: check klibs.io or the library's docs (lesson 69).

Mistake #7: Treating KMP as a UI framework. Fix: remember it shares logic; Compose Multiplatform shares UI.

Mistake #8: Copying outdated Gradle setups from old blog posts. Fix: follow the current official pages.

Mistake #9: Skipping tests in shared code. Fix: test in commonTest; one test runs on every target.

Mistake #10: Adopting without a decision record. Fix: write down scope, risks and a first step.

Question 1. What does KMP compile common Kotlin into for Android and for iOS?

Question 2. What is the difference between expect and actual?

Question 3. Why is the domain layer the best first candidate to share?

Question 4. Name two things KMP does not do.

Question 5. Which test library works in commonTest?

Go deeper: official resources

• Kotlin Multiplatform programme
• Kotlin Multiplatform on Android Developers
• Why try Kotlin Multiplatform (JetBrains)
• Search multiplatform libraries on klibs.io