Kotlin for Swift Developers

Four defaults differ, and most of this page follows from them. Swift struct and enum are value types while every Kotlin user-defined type is a reference type (immutability is by convention with val and copy()). Swift uses ARC, while Kotlin has a tracing garbage collector on every target. Swift throws is part of the signature, while Kotlin exceptions are unchecked and @Throws only affects the Objective-C/Swift export. Swift 6 checks data races at compile time, while Kotlin relies on coroutines, dispatchers and the Kotlin/Native memory manager.

For the details of each language, see Swift: Structures and Classes and Kotlin: Classes and Objects. The Swift code a shared module exposes is Objective-C-shaped today (Swift export, which maps Kotlin to Swift directly, is Alpha), so the export sections below describe both views: the Kotlin source and the Swift you will actually call.

Swift Optional<T> is an enum with two cases; Kotlin T? is a type-system feature with no wrapper object. The operators correspond almost one-to-one.

Kotlin has smart casts: after a null check the compiler treats a val (or a local var that is not captured and modified) as non-null, so no unwrapping step exists.

See Kotlin docs — Null safety and The Swift Programming Language — The Basics for the full rules, and Kotlin: Null Safety and Swift: Optionals in this repository.

What crosses the Swift boundary: Kotlin String? becomes Swift String?, a Kotlin Trail? becomes Trail?, but a nullable primitive such as Int? becomes KotlinInt? (a boxed NSNumber subclass), and a Long becomes Int64, a Double becomes Double. Generic collections of primitives, such as List<Int>, arrive as [KotlinInt]; call .int32Value or .intValue to read them. Design shared APIs with non-null String, Int and Boolean where you can, to keep the Swift side clean.

Swift struct gives you value semantics for free: assignment copies, let makes it deeply immutable, and Equatable/Hashable are synthesized. Kotlin data class gives you the API of a value type — equals, hashCode, toString, copy and destructuring — on an ordinary reference type.

The Swift view is the first surprise. The Objective-C export names the Kotlin copy as doCopy (because copy is an NSObject method), requires every argument, and loses the default values, so the Kotlin copy(isFavorite = …​) shortcut does not exist in Swift. Put such helpers in Kotlin (toggleFavorite() above) and call them from Swift as TrailFormattingKt.toggleFavorite(trail)-style top-level functions, rather than rebuilding the logic in Swift. The exported class also uses reference identity, so Swift == on exported Kotlin classes should be written as trail.isEqual(other) unless you add Equatable conformance in a Swift extension.

Copy-on-write is the other difference: Swift collections are value types, so mutating a copy never affects the original. Kotlin’s read-only List<Trail> is only a view; a MutableList can be hiding behind it. Treat shared state as immutable and replace it with a new instance, which is exactly what StateFlow<TrailListUiState> expects.

See Kotlin docs — Data classes and Kotlin: Data Classes and Destructuring.

A Swift protocol and a Kotlin interface both declare a contract that classes, structs or enums adopt. Kotlin interfaces can carry default implementations and (abstract) properties, much like protocol extensions.

Swift classes can implement exported Kotlin interfaces, and that is the clean way to inject a platform capability (for example a Swift IosLocationProvider into shared code), but they must inherit NSObject and handle the Flow and suspend shapes shown below. Default arguments (region: String? = null) are not exported, so Swift callers pass every argument. See expect/actual and Calling Platform APIs for the LocationProvider pattern.

See Kotlin docs — Interfaces, Kotlin: Inheritance and Interfaces and Swift: Protocols.

Both languages add functions and computed properties to types you do not own, resolved statically. Kotlin extension functions are plain top-level functions with a receiver; they cannot add stored properties, and they cannot override a member (a member always wins).

The Objective-C export has no concept of an extension, so Swift calls TrailExtensionsKt.favorites(trails): Kotlin extension functions appear as static methods on a class named after the file (TrailExtensionsKt), with the receiver as the first parameter. Use @file:JvmName for the JVM, and @ObjCName (Experimental, needs @OptIn(ExperimentalObjCName::class)) to give the exported class or function a Swift-friendly name. To get real Swift extensions, write them in Swift on top of the exported types.

See Kotlin docs — Extensions and Kotlin: Extension Functions and Scope Functions and Swift: Extensions and Nested Types.

Swift enums with associated values do the job of both Kotlin’s enum class (a fixed set of constants) and Kotlin’s sealed classes and interfaces (a closed set of shapes that can carry data).

Plain Objective-C export turns a sealed interface into a protocol plus unrelated classes, so Swift sees an open hierarchy and cannot check exhaustiveness. SKIE 0.10.15 (Touchlab, third-party, pre-1.0) generates an onEnum(of:) function that returns a real Swift enum, restoring switch exhaustiveness for sealed hierarchies and exported enums:

Enums are exported as Objective-C classes with static members (Difficulty.easy), so a Swift switch over a Kotlin enum is not exhaustive without SKIE either; Swift export (Alpha) maps Kotlin enums to real Swift enums.

See Kotlin docs — Enum classes, Kotlin docs — Sealed classes and interfaces, SKIE documentation and Kotlin: Sealed Classes and Enums, Swift: Enumerations.

A Swift closure and a Kotlin lambda are the same idea with different punctuation. Kotlin adds an implicit it for single-parameter lambdas and trailing lambda syntax, the equivalent of Swift’s trailing closure.

A Kotlin function type is exported as an Objective-C block. Generic parameters erase to Any and a primitive Boolean return needs boxing (KotlinBoolean), so Swift callers cast and box. Prefer exporting concrete, non-generic functions for the Swift side. Kotlin Unit becomes Void in Objective-C blocks (KotlinUnit for generics).

See Kotlin docs — Higher-order functions and lambdas and Kotlin: Lambdas and Higher-Order Functions, Swift: Closures.

Swift marks a function async and calls it with await; Kotlin marks it suspend and calls it from another suspending function or a coroutine. Both are cooperative: the function can pause without blocking its thread.

The same declaration looks different once exported (the snippet is a slice of OfflineFirstTrailRepository, which implements TrailRepository). A Kotlin suspend fun becomes an Objective-C method with a completionHandler, and Swift imports completion-handler methods as async throws automatically:

Two caveats apply. First, a Kotlin suspend function only surfaces as a Swift throws when it is annotated with @Throws (next-but-one section); without it an uncaught Kotlin exception in a suspend function terminates the app unless it is a CancellationException. Second, cancelling the Swift Task does not always cancel the underlying coroutine in plain Objective-C export; KMP-NativeCoroutines 1.0.6 (third-party) and SKIE (which maps suspend to a cancellable Swift async function) fix this. See Coroutines, Flow and Concurrency in Shared Code for dispatchers and structured concurrency, and Objective-C Interop, Swift Export and SKIE for the export rules in detail and Consuming Coroutines and Flow from Swift and SwiftUI for flows.

See Kotlin docs — Coroutines, Kotlin: Coroutines Basics, Swift: async/await and Tasks and Apple: Concurrency in Apps.

A Kotlin Flow<T> is a cold asynchronous stream, closest to Swift’s AsyncSequence (pull-style, structured) and to a Combine publisher (operators such as map, combine, debounce). StateFlow<T> is the "current value plus changes" type, closest to CurrentValueSubject or an @Published property; SharedFlow<T> is closest to PassthroughSubject.

Swift cannot call collect on a plain exported Flow ergonomically: it receives a Kotlinx_coroutines_coreFlow protocol with a callback-based collect(collector:completionHandler:), generic types erased to Any. The two community solutions turn flows into native Swift types:

With SKIE no annotation is needed: Flow is exported as a Swift AsyncSequence, so the same loop reads for await value in viewModel.uiState, and StateFlow additionally exposes a synchronous .value. Pick one tool per project; both are third-party (SKIE 0.10.15, KMP-NativeCoroutines 1.0.6). The project-wide choice is discussed in Objective-C Interop, Swift Export and SKIE; the SwiftUI side of state is covered in SwiftUI State and Data Flow.

See Kotlin docs — Asynchronous Flow, KMP-NativeCoroutines, and Kotlin: Flows.

SwiftPM manages Swift packages with a Package.swift manifest; Xcode builds the app. In a KMP project Gradle builds the Kotlin modules and hands Xcode a framework (or a SwiftPM package of one).

Three directions exist for combining the two build systems: Gradle builds a framework that Xcode embeds directly (embedAndSignAppleFrameworkForXcode), Gradle publishes an XCFramework that a Swift package references as a binary target, and Gradle consumes Swift packages through SwiftPM import (Alpha). They are detailed in Gradle Configuration, the Multiplatform DSL and Compatibility and Dependencies, klibs.io, cinterop and SwiftPM Import. For SwiftPM itself, see Swift Package Manager and Swift Packages and Modularization.

See Kotlin docs — Build final native binaries and Kotlin docs — Multiplatform Gradle DSL reference.

The two systems have similar levels but different defaults and different module boundaries.

Only public declarations of the module whose framework you build — and of modules you export() — reach Swift; internal and private never appear in the header. Use internal heavily in shared modules, and use api versus implementation dependencies deliberately, since an implementation dependency’s types do not leak into the framework unless exported. @HiddenFromObjC is Experimental (opt-in with ExperimentalObjCRefinement) and removes an otherwise public declaration from the header; @ShouldRefineInSwift goes further and makes it a __-prefixed member that you re-expose with a nicer Swift wrapper.

See Kotlin docs — Visibility modifiers, Kotlin: Classes and Objects and Swift: Access Control.

Swift’s throws is checked by the compiler. Kotlin exceptions are all unchecked; there is no throws clause and no forced try. That difference is the most dangerous one at the Swift boundary because Objective-C has no exception model that Swift can catch.

When Kotlin code is called from Swift, an exception that escapes is not a Swift error. For ordinary functions it crashes the app. For functions annotated with @Throws(SomeException::class) the exported method becomes a Swift throws function, and listed exception classes (and their subclasses) are converted to NSError; any other exception still terminates the process. For suspend functions, CancellationException is always forwarded to the completion handler, and @Throws is needed for the rest.

The more robust pattern for shared code is not to throw across the boundary at all: return a sealed result type (for example sealed interface LoadResult with Success and Failure cases, or TrailListUiState.Error shown earlier) and let Swift pattern-match it. The error-modelling guidance, including which exceptions to list, is in Architecture, Shared ViewModels and State.

See Kotlin docs — Exceptions, Kotlin docs — Interoperability with Swift/Objective-C, Kotlin: Exceptions and Error Handling and Swift: Error Handling.