Kotlin Multiplatform: cos'è, shared module e expect/actual

Cos'è Kotlin Multiplatform?

Kotlin Multiplatform è una tecnologia di compilazione incrociata che consente di scrivere codice condiviso in Kotlin e compilarlo per diverse piattaforme: JVM (Android), LLVM (iOS, macOS, watchOS), JavaScript (Web) e binari nativi (Linux, Windows). KMP non è un framework UI — risolve il problema del riutilizzo della logica di business, non delle interfacce.

L'architettura KMP è costruita attorno a un shared module — un modulo Gradle contenente commonMain con codice indipendente dalla piattaforma e source set per ogni destinazione (androidMain, iosMain, desktopMain). Secondo i dati JetBrains per il 2025, oltre il 40% dei nuovi progetti Kotlin utilizza KMP per condividere codice tra piattaforme.

Kotlin Multiplatform Mobile (KMM) — il nome precedente per lo scenario mobile iOS+Android. Da Kotlin 2.1+, il termine KMM è stato sostituito da Kotlin Multiplatform, poiché la tecnologia è andata oltre lo sviluppo mobile. Netflix, McDonald's e VMware utilizzano KMP in produzione per condividere codice tra applicazioni mobili.

Meccanismo expect/actual: architettura

Expect/actual — il meccanismo chiave di KMP per lavorare con codice specifico della piattaforma. In commonMain viene dichiarata una dichiarazione expect (funzione, classe, proprietà), e in ogni source set specifico della piattaforma (androidMain, iosMain) viene fornita un'implementazione actual. Il compilatore verifica che per ogni expect esista un actual su ogni piattaforma di destinazione.

// commonMain — dichiarazione API di piattaforma
expect fun getPlatformName(): String

expect class PlatformContext(val appVersion: String)

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

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

La gerarchia dei source set in KMP consente di creare livelli intermedi: ad esempio, iosArm64Main (dispositivi iOS fisici) e iosSimulatorArm64Main (simulatore) con iosMain condiviso. Il codice da commonMain è disponibile per tutte le piattaforme, mentre il codice da iosMain è disponibile solo per le destinazioni iOS. Ciò riduce la duplicazione quando l'implementazione differisce non per ogni piattaforma ma per un gruppo di piattaforme.

In pratica, expect/actual viene utilizzato per: accedere all'archiviazione locale (SharedPreferences vs NSUserDefaults), rete (HttpEngine per piattaforma), accesso al filesystem, crittografia e analisi. JetBrains raccomanda di ridurre al minimo il numero di dichiarazioni expect/actual e di spostare quanto più codice possibile in commonMain.

Shared module: struttura e Gradle

Shared module — un modulo Gradle standard con il plugin org.jetbrains.kotlin.multiplatform. Contiene codice condiviso in src/commonMain/kotlin/ e implementazioni specifiche della piattaforma in src/androidMain/kotlin/ e src/iosMain/kotlin/. Un progetto KMP include anche androidApp e iosApp, che dipendono dallo 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")
            }
        }
    }
}

La configurazione di Gradle per KMP richiede la dichiarazione esplicita delle destinazioni iOS — x64 (simulatore Intel), arm64 (dispositivi fisici) e simulatorArm64 (simulatore Apple Silicon). Per ogni destinazione viene generato un framework Apple separato. Il plugin kotlin("multiplatform") configura automaticamente la compilazione per JVM e LLVM in base alle destinazioni dichiarate.

Ktor e kotlinx.serialization — librerie KMP standard che supportano il codice condiviso. Ktor fornisce un client HTTP con motori per ogni piattaforma (OkHttp per Android, Darwin per iOS). kotlinx.serialization funziona su tutte le piattaforme senza expect/actual grazie alla sua implementazione multipiattaforma in commonMain.

Integrazione iOS tramite Kotlin/Native

Kotlin/Native — un compilatore Kotlin per codice nativo tramite LLVM. Per iOS, lo shared module viene compilato in un framework Apple (.framework) che viene collegato tramite Xcode. La chiamata al codice condiviso da Swift/Objective-C avviene tramite gli header Objective-C generati, quindi l'API dello shared module deve essere compatibile con Objective-C.

Limitazioni dell'integrazione iOS: le collezioni Kotlin (List, Map) vengono convertite in NSArray/NSDictionary. Le funzioni con parametri predefiniti non vengono esportate — sono necessari overloads. Per le funzioni suspend, vengono generati metodi basati su callback con @ObjCName e supporto async/await da Kotlin 2.0+.

// App iOS: chiamata allo shared module da 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)")
            }
        })
    }
}

L'integrazione dello shared module in Xcode avviene tramite embed-and-framework — il .xcframework generato viene aggiunto al progetto Xcode. Il plugin Gradle può aggiornare automaticamente il framework durante la compilazione tramite embedAndSignAppleFrameworkForXcode. Per testare sul simulatore, è sufficiente un binario iosSimulatorArm64 o iosX64.

KMP vs Flutter vs React Native

La scelta tra KMP, Flutter e React Native dipende dalla priorità: riutilizzo del codice o multipiattaforma completa. KMP fornisce UI nativa su ogni piattaforma ma richiede due basi di codice per l'interfaccia. Flutter e React Native utilizzano un'unica UI ma sacrificano la nativeità.

Quando scegliere KMP: il progetto richiede UI ad alte prestazioni (giochi, mappe, animazioni), il codice nativo esistente deve essere riutilizzato, il team conosce già Kotlin e le piattaforme native. Quando scegliere Flutter/RN: MVP o startup con budget limitato, team monoprofilo, l'UI non richiede personalizzazione nativa profonda.

Strumenti e librerie KMP

L'ecosistema di strumenti KMP include librerie per tutti i livelli dell'applicazione: rete (Ktor), serializzazione (kotlinx.serialization), database (SQLDelight), navigazione (Decompose), DI (Koin) e archiviazione dati (multiplatform-settings). JetBrains supporta Compose Multiplatform — un framework UI in Kotlin che funziona su tutte le piattaforme.

// Repository KMP con 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 — un framework UI per KMP basato su Jetpack Compose. Consente di scrivere interfacce in Kotlin per Android, iOS, Desktop e Web. Nel 2025, Compose Multiplatform ha raggiunto lo stato stabile per Android e Desktop; la destinazione iOS è in beta. Per i progetti di produzione con UI nativa, il vantaggio di KMP rimane la principale differenza da Flutter.