Dependencies, klibs.io, cinterop and SwiftPM Import

The official documentation splits dependencies into two kinds, and the split drives where you declare them.

The rule of thumb: put everything you can in commonMain, and add a platform-specific dependency only where common code cannot reach a platform API itself. Platform dependencies are the hand-written side of the expect/actual and platform API story.

Dependencies belong to a source set, not to the module as a whole. This is the main difference from a plain Android module, where implementation(…​) at the top level applies to everything. The recommended way to manage coordinates is a Gradle version catalog, shown here for the shared module:

See Kotlin docs — Adding dependencies on multiplatform libraries.

Those entries are then attached to source sets in the shared module’s build script:

See Kotlin docs — Adding dependencies on multiplatform libraries.

Three details deserve emphasis.

The client engine pattern above is worth remembering because it recurs: the API artifact (ktor-client-core) goes into commonMain, and the engine (ktor-client-okhttp, ktor-client-darwin) goes into the platform source sets. The same shape applies to SQLDelight drivers and to many libraries that wrap a platform SDK. For the Android counterpart of this setup see Project Structure, Gradle and Build Variants.

A multiplatform library is published as several artifacts that Gradle treats as one logical module.

When Gradle resolves commonMain.dependencies { implementation(libs.ktor.client.core) } it does this once for the metadata compilation, and again for every target compilation, each time matching that compilation’s attributes to a variant. You never write -iosarm64 yourself.

The practical consequences follow directly from this model.

https://klibs.io/ is the Kotlin Multiplatform library catalog. It indexes libraries published on GitHub and Maven Central, then tags and categorizes them by supported platforms so that you can filter for, say, "iOS and Wasm" before choosing. Each library page renders the project’s README and adds information such as the number of dependents, project activity and licenses.

Use it as a checklist when picking a dependency:

With the com.android.kotlin.multiplatform.library plugin, an Android dependency is declared the same way as any other platform dependency: in the Android source set. The documentation recommends androidMain:

See Kotlin docs — Adding Android dependencies.

When you migrate an Android module, a dependency such as debugImplementation(…​) has no top-level equivalent: you add an implementation dependency to the source set named androidDebug instead. To keep Android dependencies together and avoid that confusion, the documentation also offers a dependencies {} block nested in the android {} block:

See Kotlin docs — Adding Android dependencies.

The documentation strongly advises against an Android-style top-level dependencies {} block at the end of the script, because mixing it with per-source-set declarations for other targets causes confusion. Under AGP 9 the plugin also has no build types or flavors, so debugImplementation and friends are replaced by the androidDebug-style source sets and by the androidApp module (see The Android Target: the Android-KMP Library Plugin and AGP 9). The Compose, Room and Play Services setup of a native app is in Project Structure, Gradle and Build Variants.

Apple SDK frameworks such as Foundation, UIKit, CoreLocation and Core Bluetooth are available to Kotlin/Native as prebuilt platform libraries, with no configuration at all (see expect/actual and Calling Platform APIs). Everything beyond Apple’s own SDKs, such as Firebase, Google Maps or a third-party framework, requires you to choose one of three mechanisms.

A constraint applies to all three: Kotlin supports interoperability with Objective-C dependencies, and with Swift dependencies only if their API is exported to Objective-C with @objc. Pure Swift APIs cannot be called directly from Kotlin; wrap them in a small Swift adapter in the iOS app and inject it into shared code through an interface (see the interface-with-platform-implementation pattern in expect/actual). Swift export (Alpha) is the opposite direction (Kotlin to Swift) and is covered in Objective-C and Swift Interop.

See Kotlin docs — Adding iOS dependencies.

Kotlin Symbol Processing (KSP) generates code for libraries such as Room, Koin Annotations and Metro. On Kotlin/Native the older kapt is not available, so KSP is the route for annotation processing. In a multiplatform module the processor dependency is added per target, through configurations named ksp<Target>, because each target is compiled separately. Since KSP 2 the catch-all ksp(…​) configuration is deprecated; configure each target explicitly so that processors do not run where they are not needed.

The shape for TrailMate with Room 3’s compiler (the processor library name is the one from the Room KMP page; use the coordinates listed there):

See Kotlin docs — KSP with Kotlin Multiplatform.

The processor path can also be a project, add("kspAndroid", project(":local-processor")), and a target may have several processors. When many iOS targets share the same processor you can loop over them:

See Kotlin docs — KSP with Kotlin Multiplatform.

Each target and compilation (main and test) gets its own symbol-processing task, created only where a processor configuration exists. To run processors in tests, add them to the test configurations: kspIosArm64Test, kspAndroidHostTest or kspAndroidDeviceTest. To list every KSP configuration your module has, run:

See Kotlin docs — KSP with Kotlin Multiplatform.

The configuration kspCommonMainMetadata is the one libraries use for code that must be generated into the common source set (the metadata compilation), for example factories or DI components that common code calls directly. Whether a processor supports it is a property of that processor, so follow its own documentation: Room and Koin Annotations each describe which ksp<Target> and kspCommonMainMetadata entries they need. If common code references a generated class and you only configured the platform configurations, the metadata compilation cannot see it, which shows as an "unresolved reference" in commonMain while platform builds succeed. See Dependency Injection with Koin and Metro and Local Storage for per-library configurations, and Project Structure, Gradle and Build Variants for the Android-only KSP and kapt migration.

Each source set has the usual Gradle configurations, and the choice matters more than in an Android module because of the iOS framework.

For a Kotlin consumer, api simply means "consumers can see these types". For iOS the picture is different, because a Kotlin/Native framework is a closed binary with an Objective-C header. Only the declarations you choose to export appear in that header, regardless of api or implementation:

See Kotlin docs — Build final native binaries.

In Swift, an exported dependency’s types are then usable through the framework’s module:

See Kotlin docs — Build final native binaries.

The decision table below gathers the practical guidance.

Exporting is not free: every exported dependency enlarges the header and the exposed API, so export the minimum, or wrap types in your own DTOs (see Objective-C and Swift Interop). Sharing two modules into one iOS app is a related case: each module producing its own framework duplicates the Kotlin runtime and dependencies, so the usual answer is an umbrella framework that exports both; see Project Structure, Targets, Source Sets and the Hierarchy Template and iOS Integration Options.