skip to content

Platform-Specific Implementations

Multiplatform libraries expose one common API and swap the implementation per target: a different HTTP engine, a different database driver, a different main dispatcher. Understanding the pattern lets you apply it in your own shared modules.

part ofKotlinread it →
on this pageshow

questions

5

In Kotlin Multiplatform, what do the `expect` and `actual` keywords do, and why does a library use them to back one common API across targets?

level: juniorimportance: must knowfreq 70%

answer

  1. expect = declaration no body in commonMain
  2. actual = real impl per platform source set
  3. compile-time link, not reflection
  4. every target must supply an actual
  5. actual typealias reuses a native type

basics

~10 s

expect declares a shared API in common code with no body; each platform (Android, iOS, JS) provides an actual implementation. So you call one function everywhere and the right platform version runs.

solid answer

~40 s

Kotlin Multiplatform splits code into a `commonMain` source set plus platform source sets (e.g. `androidMain`, `iosMain`, `jsMain`). In `commonMain` you write `expect fun`/`expect class`/`expect val` — a declaration with no implementation. Each platform source set must supply a matching `actual` with the same signature, fully implemented. At compile time the compiler links the common `expect` to the platform's `actual`, so the final binary for that target contains a real implementation. Libraries use this to expose ONE common API (e.g. `Dispatchers.Main`, an HTTP client, a database driver) while delegating to platform-native primitives underneath — UI loopers on Android, NSRunLoop on iOS. Callers in common code stay platform-agnostic; only the library's internals branch. It is resolved statically, not via runtime reflection.

code

kotlin · 10 lines
kotlin
// commonMain
expect fun currentTimeMillis(): Long

// androidMain / jvmMain
actual fun currentTimeMillis(): Long = System.currentTimeMillis()

// iosMain
import platform.Foundation.NSDate
actual fun currentTimeMillis(): Long =
    (NSDate().timeIntervalSince1970 * 1000).toLong()

go deeper

for a junior

Knows expect declares, actual implements, one per platform; can give a simple example.

for a middle

Explains source sets, compile-time linking, and that every target must supply an actual.

for a senior

Adds actual typealias, intermediate source-set actuals via the hierarchy, and how real libraries apply it.

for a principal

Discusses API-design tradeoffs of expect/actual vs interface injection, exhaustiveness guarantees, and binary/ABI implications across targets.

## What problem this solves Kotlin Multiplatform (KMP) lets you share one body of Kotlin code across **targets** (JVM/Android, Apple/iOS via Kotlin/Native, JS, etc.). But some functionality has no portable implementation — getting the UI thread, opening a socket, reading a file. The `expect`/`actual` mechanism lets a library publish **one common API** and back it with a **different real implementation per target**. ## Source sets KMP code is organized into **source sets**: - `commonMain` — shared code compiled for every target. - platform sets like `androidMain`, `iosMain` (often `iosX64Main`/`iosArm64Main` merged via a hierarchy), `jsMain`, `jvmMain`. ## `expect` — the contract In `commonMain` you write a declaration with **no body**: ```kotlin // commonMain expect val platformName: String expect fun randomUUID(): String expect class Platform() { val name: String } ``` You can `expect` on `fun`, `val`, `class`, `object`, `interface`, even `annotation class` and `enum`. ## `actual` — the implementation Each target source set MUST provide a matching `actual` with the **same signature**: ```kotlin // androidMain actual val platformName: String = "Android ${android.os.Build.VERSION.SDK_INT}" actual fun randomUUID(): String = java.util.UUID.randomUUID().toString() actual class Platform actual constructor() { actual val name: String = "Android" } ``` ```kotlin // iosMain import platform.Foundation.NSUUID actual val platformName: String = "iOS" actual fun randomUUID(): String = NSUUID().UUIDString() ``` ## Key properties - **Compile-time linking, not reflection.** The compiler matches `expect` to `actual` when building each target; the resulting binary contains only that target's code. There is no runtime dispatch or service lookup. - **Exhaustive.** If any target lacks an `actual`, compilation of that target fails. Common code can never call an unimplemented API. - **`actual typealias`.** A platform can satisfy an `expect class` by aliasing an existing platform type: `actual typealias UUID = java.util.UUID`. This reuses the native class directly. - **Hierarchy & defaults.** With the default hierarchy template, intermediate sets (e.g. `appleMain`) can hold shared `actual`s for several Apple targets. Modern Kotlin also allows `expect` declarations with default bodies that a target may override. ## How libraries use it - **kotlinx.coroutines** exposes `Dispatchers.Main` as a common API; the JVM/Android `actual` uses the main `Looper`/`Handler`, the JS `actual` uses the microtask/event loop, Native uses the main run loop. - **Ktor** has a common `HttpClient`; engines (`OkHttp`, `Darwin`, `Js`, `CIO`) are the platform-specific backends selected per target. - **SQLDelight** exposes a common `SqlDriver`; `AndroidSqliteDriver`, `NativeSqliteDriver`, and a JS/Web worker driver are the actuals. The takeaway: `expect`/`actual` is the seam that keeps **call sites portable** while letting the implementation be **native per platform**.

  • What happens if one target is missing an `actual` for an `expect` declaration?
    Compilation of that specific target fails with an unresolved-expectation error; you cannot ship a binary without supplying every actual.
  • Can an `actual` be a typealias?
    Yes. `actual typealias Platform = SomeNativeType` satisfies an `expect class` by reusing an existing platform type, avoiding a hand-written wrapper.

Like an interface (expect) whose concrete class (actual) is chosen by which platform you compile for, decided at build time rather than runtime.

  • Saying expect/actual is resolved at runtime via reflection or service loaders
  • Thinking you only need an actual on 'the main' platform
  • Confusing expect/actual with regular interface/implementation chosen at runtime
  • Believing common code can call an expect with no actuals supplied
  • Claiming actual signatures may differ from the expect

context

open as a page

How is `Dispatchers.Main` from kotlinx.coroutines backed differently on Android, iOS, and JS, and what must Android consumers add for it to work?

level: middleimportance: should knowfreq 55%

basics

~20 s

Dispatchers.Main is one common name, but each platform runs it on its own UI loop: Android's main Handler, iOS's main run loop, JS's event loop. On Android you must add the kotlinx-coroutines-android artifact so the real Main dispatcher is present.

open as a page

Ktor's `HttpClient` is a common API, but you must pick an engine per target. Explain the engine model and name appropriate engines for Android, iOS, and JS.

level: middleimportance: should knowfreq 50%

basics

~20 s

Ktor gives you one common HttpClient, but the actual network calls run through a pluggable engine you choose per platform: OkHttp or CIO on Android, Darwin on iOS, Js on the web. You configure the client in shared code and supply the engine per target.

open as a page

SQLDelight generates a common database API but needs a platform `SqlDriver`. Name the drivers per platform and explain how the generated `Database` is constructed from one.

level: seniorimportance: should knowfreq 40%

basics

~20 s

SQLDelight turns your .sq files into a common typed database API, but you must hand it a platform-specific SqlDriver to actually talk to SQLite: Android, native (iOS), and a web/JS driver. You build the driver per platform and pass it into the generated Database.

open as a page

When designing a KMP library's public surface, when should you use `expect`/`actual` versus a plain interface with platform-supplied implementations? What are the tradeoffs?

level: principalimportance: nice to knowfreq 25%

basics

~20 s

Use expect/actual when there is exactly one natural implementation per platform that callers shouldn't choose. Use a plain interface injected per platform when you want multiple implementations, easy mocking, or looser coupling. Interfaces are more flexible; expect/actual is more rigid but compiler-enforced.

open as a page