Kotlin Multiplatform: o que é, shared module e expect/actual

O que é Kotlin Multiplatform?

Kotlin Multiplatform é uma tecnologia de compilação cruzada que permite escrever código compartilhado em Kotlin e compilá-lo para diferentes plataformas: JVM (Android), LLVM (iOS, macOS, watchOS), JavaScript (Web) e binários nativos (Linux, Windows). KMP não é um framework de UI — ele resolve o problema de reutilizar a lógica de negócios, não as interfaces.

A arquitetura KMP é construída em torno de um shared module — um módulo Gradle contendo commonMain com código independente de plataforma e source sets para cada destino (androidMain, iosMain, desktopMain). De acordo com dados da JetBrains para 2025, mais de 40% dos novos projetos Kotlin usam KMP para compartilhar código entre plataformas.

Kotlin Multiplatform Mobile (KMM) — o nome anterior para o cenário móvel iOS+Android. Desde Kotlin 2.1+, o termo KMM foi substituído por Kotlin Multiplatform, pois a tecnologia ultrapassou o desenvolvimento móvel. Netflix, McDonald's e VMware usam KMP em produção para compartilhar código entre aplicativos móveis.

Mecanismo expect/actual: arquitetura

Expect/actual — o mecanismo chave do KMP para trabalhar com código específico de plataforma. No commonMain, uma declaração expect (função, classe, propriedade) é declarada, e em cada source set específico de plataforma (androidMain, iosMain), uma implementação actual é fornecida. O compilador verifica se para cada expect existe um actual em cada plataforma de destino.

// commonMain — declaração de API de plataforma
expect fun getPlatformName(): String

expect class PlatformContext(val appVersion: String)

// androidMain — actual para Android
actual fun getPlatformName(): String = "Android \${Build.VERSION.SDK_INT}"

// iosMain — actual para iOS
actual fun getPlatformName(): String =
    UIDevice.currentDevice.systemName

A hierarquia de source sets no KMP permite criar níveis intermediários: por exemplo, iosArm64Main (dispositivos iOS físicos) e iosSimulatorArm64Main (simulador) com iosMain compartilhado. O código do commonMain está disponível para todas as plataformas, enquanto o código do iosMain está disponível apenas para destinos iOS. Isso reduz a duplicação quando a implementação difere não para cada plataforma, mas para um grupo de plataformas.

Na prática, expect/actual é usado para: acessar armazenamento local (SharedPreferences vs NSUserDefaults), redes (HttpEngine por plataforma), acesso ao sistema de arquivos, criptografia e análise. A JetBrains recomenda minimizar o número de declarações expect/actual e mover o máximo de código possível para o commonMain.

Shared module: estrutura e Gradle

Shared module — um módulo Gradle padrão com o plugin org.jetbrains.kotlin.multiplatform. Ele contém código compartilhado em src/commonMain/kotlin/ e implementações específicas de plataforma em src/androidMain/kotlin/ e src/iosMain/kotlin/. Um projeto KMP também inclui androidApp e iosApp, que dependem do shared module.

// build.gradle.kts — shared module
plugins {
    kotlin("multiplatform")
    id("com.android.library")
}

kotlin {
    androidTarget()
    
    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach {
        it.binaries.framework {
            baseName = "shared"
            isStatic = true
        }
    }

    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("io.ktor:ktor-client-core:3.1.0")
                implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
            }
        }
        val androidMain by getting {
            dependencies {
                implementation("io.ktor:ktor-client-okhttp:3.1.0")
            }
        }
        val iosMain by creating {
            dependencies {
                implementation("io.ktor:ktor-client-darwin:3.1.0")
            }
        }
    }
}

A configuração do Gradle para KMP requer a declaração explícita dos destinos iOS — x64 (simulador Intel), arm64 (dispositivos físicos) e simulatorArm64 (simulador Apple Silicon). Um framework Apple separado é gerado para cada destino. O plugin kotlin("multiplatform") configura automaticamente a compilação para JVM e LLVM de acordo com os destinos declarados.

Ktor e kotlinx.serialization — bibliotecas KMP padrão que suportam código compartilhado. Ktor fornece um cliente HTTP com mecanismos para cada plataforma (OkHttp para Android, Darwin para iOS). kotlinx.serialization funciona em todas as plataformas sem expect/actual graças à sua implementação multiplataforma no commonMain.

Integração com iOS via Kotlin/Native

Kotlin/Native — um compilador Kotlin para código nativo via LLVM. Para iOS, o shared module é compilado em um framework da Apple (.framework) que é conectado via Xcode. A chamada ao código compartilhado do Swift/Objective-C ocorre através dos cabeçalhos Objective-C gerados, portanto a API do shared module deve ser compatível com Objective-C.

Limitações da integração iOS: as coleções Kotlin (List, Map) são convertidas em NSArray/NSDictionary. Funções com parâmetros padrão não são exportadas — são necessárias sobrecargas. Para funções suspend, métodos baseados em callback são gerados com @ObjCName e suporte async/await a partir do Kotlin 2.0+.

// Aplicativo iOS: chamando shared module do Swift
import shared

class ViewModel: ObservableObject {
    let repository = UserRepository()
    
    func loadUsers() {
        repository.fetchUsers(completionHandler: { result, error in
            if let users = result as? [User] {
                print("Users: \(users.count)")
            }
        })
    }
}

A integração do shared module no Xcode ocorre via embed-and-framework — o .xcframework gerado é adicionado ao projeto Xcode. O plugin Gradle pode atualizar automaticamente o framework durante a compilação via embedAndSignAppleFrameworkForXcode. Para teste no simulador, um binário iosSimulatorArm64 ou iosX64 é suficiente.

KMP vs Flutter vs React Native

A escolha entre KMP, Flutter e React Native depende da prioridade: reutilização de código ou plataforma cruzada completa. KMP fornece UI nativa em cada plataforma, mas requer duas bases de código para a interface. Flutter e React Native usam uma única UI, mas sacrificam a natividade.

Quando escolher KMP: o projeto requer UI de alto desempenho (jogos, mapas, animações), é necessário reutilizar código nativo existente, a equipe já conhece Kotlin e plataformas nativas. Quando escolher Flutter/RN: MVP ou startup com orçamento limitado, equipe de perfil único, a UI não requer personalização nativa profunda.

Ferramentas e bibliotecas KMP

O ecossistema de ferramentas KMP inclui bibliotecas para todas as camadas do aplicativo: redes (Ktor), serialização (kotlinx.serialization), banco de dados (SQLDelight), navegação (Decompose), DI (Koin) e armazenamento de dados (multiplatform-settings). A JetBrains oferece suporte ao Compose Multiplatform — um framework de UI em Kotlin que funciona em todas as plataformas.

// Repositório KMP com SQLDelight + Ktor
class UserRepository(
    private val httpClient: HttpClient,
    private val db: AppDatabase
) {
    suspend fun syncUsers(): List<User> {
        val remote = httpClient.get("https://api.example.com/users")
            .body<List<UserDto>>()
        
        db.userQueries.replaceAll(remote.map { it.toDomain() })
        
        return db.userQueries.selectAll().executeAsList()
    }
}

Compose Multiplatform — um framework de UI para KMP baseado no Jetpack Compose. Permite escrever interfaces em Kotlin para Android, iOS, Desktop e Web. Em 2025, o Compose Multiplatform atingiu o status estável para Android e Desktop; o destino iOS está em beta. Para projetos de produção com UI nativa, a vantagem do KMP continua sendo a principal diferença do Flutter.