Kotlin Multiplatform: The Smallest POC That Proves Value

Quickstart: the smallest KMP POC you can ship this week

If you’re trying Kotlin Multiplatform for the first time, don’t start by sharing UI. Start by sharing the “plumbing” that’s duplicated today: JSON models, API calls, and error handling. This quickstart is designed to be small enough to finish quickly, but real enough to show measurable value.

Minimal shared module setup (Gradle)

This is the only “setup-heavy” part of the smallest Kotlin Multiplatform POC. Keep the dependency list tight: serialization + Ktor client + coroutines. Everything else can come later (DI, caching, analytics, persistence).

plugins {
  kotlin("multiplatform")
  kotlin("plugin.serialization")
}

kotlin {
  androidTarget()

  // Generates an iOS framework you can import into Xcode.
  iosX64()
  iosArm64()
  iosSimulatorArm64()

  sourceSets {
    val commonMain by getting {
      dependencies {
        implementation("io.ktor:ktor-client-core:YOUR_KTOR_VERSION")
        implementation("io.ktor:ktor-client-content-negotiation:YOUR_KTOR_VERSION")
        implementation("io.ktor:ktor-serialization-kotlinx-json:YOUR_KTOR_VERSION")
        implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:YOUR_SERIALIZATION_VERSION")
        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:YOUR_COROUTINES_VERSION")
      }
    }

    val androidMain by getting {
      dependencies {
        implementation("io.ktor:ktor-client-okhttp:YOUR_KTOR_VERSION")
      }
    }

    val iosMain by creating {
      dependsOn(commonMain)
      dependencies {
        implementation("io.ktor:ktor-client-darwin:YOUR_KTOR_VERSION")
      }
    }

    iosX64Main.dependsOn(iosMain)
    iosArm64Main.dependsOn(iosMain)
    iosSimulatorArm64Main.dependsOn(iosMain)
  }
}

Overview

Kotlin Multiplatform (KMP) is best treated as an incremental engineering tool, not a belief system. The smallest POC that proves value should answer four questions:

• Can we share code that is currently duplicated? (models, parsing, error mapping, networking)
• Does it reduce drift? (Android and iOS behave the same for the same API)
• Is the integration experience acceptable? (build times, Xcode/Gradle friction, debugging)
• Can we keep UI native? (Compose + SwiftUI remain first-class)

By the end, you’ll have a repeatable pattern: add an endpoint once, update both platforms, and keep platform UI and platform-specific UX behaviors completely native. That’s usually the “aha moment” that makes Kotlin Multiplatform feel worth it.

Core concepts

Before you write the POC, it helps to have a shared mental model. Kotlin Multiplatform is not “one codebase for two apps.” It’s a way to compile Kotlin into platform-specific artifacts while sharing selected modules. The goal is to share the parts that benefit from being identical, and keep the parts that benefit from being native.

1) The “public surface area” rule

Your KMP module has two audiences: Android and iOS. Anything you expose publicly becomes a contract you’ll support. A good smallest POC keeps the public API tiny: DTOs + one repository + a small sealed error type.

2) Common code vs platform code (where the line usually is)

A simple rule: share code where identical behavior is valuable; keep code native where platform UX matters. For most teams, the sweet spot is: networking + models + error mapping + (optional) light business rules.

3) Ktor engines and why you need them

Ktor provides a common API, but each platform uses a different underlying HTTP engine. That’s why the dependency setup includes ktor-client-okhttp for Android and ktor-client-darwin for iOS. You write one HTTP client in common code; the platform selects the engine at compile time.

4) Coroutines, thread rules, and iOS expectations

Coroutines are a great fit for shared networking, but iOS integration is where POCs often get messy. You want a clear story for:

• How Swift calls suspend functions (callback wrappers or async/await interop)
• Where results are delivered (main thread for UI updates)
• How cancellation works (user navigates away, request should stop)

Step-by-step

This is a practical guide you can follow even if you already have existing Android and iOS apps. The steps below focus on the smallest Kotlin Multiplatform POC that proves value: one endpoint, shared models, shared networking, and native UI on both platforms.

Step 1 — Choose your POC slice (scope it like a feature flag)

Step 2 — Define your contract: DTOs + errors + repository

The contract is the heart of the smallest POC. If you design it well, both apps will adopt it without fighting it. If you design it poorly, the POC will “work” but feel painful.

Step 3 — Implement shared networking + repository (the core POC)

Below is a compact “KMP POC” implementation that stays intentionally small: a Ktor client with JSON negotiation, a DTO, a sealed error type, and a repository that returns a typed result. You can grow this later (auth refresh, retries, caching), but don’t add those until you’ve proven the basic flow.

import io.ktor.client.HttpClient
import io.ktor.client.call.body
import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
import io.ktor.client.request.get
import io.ktor.client.request.header
import io.ktor.serialization.kotlinx.json.json
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json

@Serializable
data class FeedItemDto(
  val id: String,
  val title: String,
  @SerialName("created_at") val createdAt: String,
  val author: String = "Unknown"
)

sealed class ApiError {
  data object Offline : ApiError()
  data object Timeout : ApiError()
  data class Http(val code: Int, val message: String? = null) : ApiError()
  data class Unknown(val message: String? = null) : ApiError()
}

sealed class ApiResult<out T> {
  data class Ok<T>(val value: T) : ApiResult<T>()
  data class Err(val error: ApiError) : ApiResult<Nothing>()
}

class ApiClient(
  private val baseUrl: String,
  private val tokenProvider: () -> String?
) {
  private val json = Json {
    ignoreUnknownKeys = true
    explicitNulls = false
    isLenient = true
  }

  private val http = HttpClient {
    install(ContentNegotiation) {
      json(json)
    }
  }

  suspend fun fetchFeed(): ApiResult<List<FeedItemDto>> = safeCall {
    val token = tokenProvider()
    val url = "$baseUrl/feed"
    val response = http.get(url) {
      if (token != null) header("Authorization", "Bearer $token")
      header("Accept", "application/json")
    }
    ApiResult.Ok(response.body())
  }

  private suspend fun <T> safeCall(block: suspend () -> ApiResult<T>): ApiResult<T> {
    return try {
      block()
    } catch (t: Throwable) {
      // Keep the POC mapping intentionally simple. Expand later based on real failures.
      val msg = t.message
      ApiResult.Err(ApiError.Unknown(msg))
    }
  }
}

interface FeedRepository {
  suspend fun loadFeed(): ApiResult<List<FeedItemDto>>
}

class FeedRepositoryImpl(private val api: ApiClient) : FeedRepository {
  override suspend fun loadFeed(): ApiResult<List<FeedItemDto>> = api.fetchFeed()
}

Step 4 — Integrate on Android (native UI, shared data)

The Android side should feel normal: call the shared repository from a ViewModel, map DTOs to UI models, and handle loading/error states exactly how you already do. The POC is successful when Android devs say “this feels like calling any other Kotlin library.”

Step 5 — Integrate on iOS (make async feel native)

iOS integration success is less about networking and more about developer experience: can Swift call the shared module cleanly, cancel work when needed, and update UI on the main thread? For a smallest POC, you want a thin Swift wrapper that makes shared code feel like a normal async API.

import Foundation
import Shared // Your generated KMP framework/module name

@MainActor
final class FeedViewModel: ObservableObject {
  @Published private(set) var items: [FeedItemDto] = []
  @Published private(set) var errorText: String? = nil
  @Published private(set) var isLoading: Bool = false

  private let repo: FeedRepository

  init(repo: FeedRepository) {
    self.repo = repo
  }

  func load() async {
    isLoading = true
    defer { isLoading = false }

    do {
      // In many setups, suspend functions are available as async in Swift.
      // If your project exposes callbacks instead, wrap them here once and keep the rest of the app clean.
      let result = try await repo.loadFeed()
      if let ok = result as? ApiResultOk {
        // ApiResultOk is the Swift-visible type name generated by KMP tooling.
        self.items = ok.value as? [FeedItemDto] ?? []
        self.errorText = nil
      } else if let err = result as? ApiResultErr {
        self.errorText = "Couldn’t load feed. Please try again."
        print("KMP error:", err.error)
      } else {
        self.errorText = "Unexpected response."
      }
    } catch {
      self.errorText = "Request failed: \(error.localizedDescription)"
    }
  }
}

Step 6 — Add a tiny “drift test” to prove the payoff

Drift is the hidden cost Kotlin Multiplatform can eliminate: Android and iOS behave differently because parsing, defaults, and error mapping are duplicated. A great POC makes drift reduction visible.

Step 7 — Decide your next move (without turning it into a rewrite)

After the POC, you should have real answers: build friction, integration pain points, and whether the “one change updates both apps” workflow feels good. Now choose a measured next step:

Common mistakes

Most failed Kotlin Multiplatform POCs fail for one of two reasons: the scope is too big, or the integration experience is ignored until late. Here are the pitfalls that show up repeatedly—and the fixes that keep your POC small and valuable.

FAQ

What should the smallest Kotlin Multiplatform POC share first?

Share API models + networking + error mapping. That combo removes duplication quickly, reduces behavior drift, and keeps your UI fully native. It also keeps the POC scope small enough to finish without turning into a rewrite.

Should a first KMP POC share UI?

Usually no. UI-sharing introduces bigger decisions (design systems, navigation patterns, platform UX differences) that can derail a POC. Prove value with shared data plumbing first; consider shared UI later only if it clearly helps your product.

How do we avoid exposing “weird” generated APIs to Swift?

Add a tiny Swift adapter layer that wraps the shared module into clean Swift async functions and domain-friendly types. Wrap it once, then keep the rest of your iOS app idiomatic Swift/SwiftUI.

Is Kotlin Multiplatform worth it if we already have stable Android/iOS code?

It can be—especially if you frequently add endpoints, change models, or fight behavior mismatches. If your apps rarely change, or if platform teams are completely independent with minimal duplication, the ROI may be lower. The smallest POC is the right way to find out without committing.

What is the biggest risk in a Kotlin Multiplatform proof of concept?

Scope creep. The moment the POC tries to solve architecture, caching, and UI, you can’t tell whether KMP is helping or whether you’re just doing a large refactor. Keep the public surface small and focus on one feature slice.

How do we handle authentication in the smallest POC?

Keep it minimal: inject a token provider and add an Authorization header. Avoid refresh flows until the basic loop works. Once the POC proves value, you can centralize token refresh and retry behavior in shared code safely.

Cheatsheet

Use this as a “scan and execute” checklist when you’re building or reviewing a Kotlin Multiplatform POC.

Wrap-up

The smallest Kotlin Multiplatform POC that proves value is not a demo app and not a rewrite. It’s a real slice of your product that removes duplication where it hurts most: shared models and shared networking. If your team can add an endpoint once and have both apps behave the same, you’ve already captured the core value.

Related posts

• Jetpack Compose: State, Effects, and UI That Doesn’t Jitter
• Kotlin Tips That Make Code Cleaner (Nulls, Scopes, Sealed Types)
• SwiftUI Layout: The Rules That Stop the ‘Why Is It Doing That?’
• iOS Architecture That Scales: MVVM, DI, and Feature Modules
• Make iOS Apps Smooth: Instruments Profiling Starter Guide
• Android Studio Profilers: Fix the 90% of Slowdowns