KSP library and Gradle plugin for generating ComposeUIViewController and UIViewControllerRepresentable files when using Compose Multiplatform for iOS.

As the project expands, the codebase required naturally grows, which can quickly become cumbersome and susceptible to errors. To mitigate this challenge, this library leverages Kotlin Symbol Processing to automatically generate the necessary Kotlin and Swift code for you.

It can be used for simple and advanced use cases.

In simple scenarios, the rendering and state management of the @Composable or UIViewController are handled entirely within a single platform — either in the shared KMP module or directly in the iOS app. It's simply a matter of embedding the component in one platform or the other, with no cross-platform coordination required.

In advanced scenarios, rendering and state management are collaborative between platforms. Certain operations — such as emitting state updates or embedding a @Composable or UIViewController — can be delegated from one platform to the other. This enables more complex integrations, where state and UI responsibilities are shared or transferred as needed between the KMP module and the iOS app.

Kotlin Multiplatform and Compose Multiplatform are built upon the philosophy of incremental adoption and sharing only what you require. Consequently, the support for this specific use-case - in my opinion - is of paramount importance, especially in its capacity to entice iOS developers to embrace Compose Multiplatform.

[!NOTE] This library takes care of the heavy lifting for you, but if you're interested in understanding how it works, the detailed approach is explained here: Compose Multiplatform — Managing UI State on iOS.

Configure the plugins block with the following. Once added, you can use the ComposeUiViewController block to set up the plugin's configuration.

plugins {
    id("org.jetbrains.kotlin.multiplatform")
    id("io.github.guilhe.kmp.plugin-composeuiviewcontroller") version "$LASTEST_VERSION"
}

ComposeUiViewController {
    iosAppName = "Gradient"
    targetName = "Gradient"
}

With this setup, all necessary configurations are automatically applied. You only need to adjust the ComposeUiViewController block to match your project settings (e.g. iosAppName and targetName). If you wish to change the default values, check the available parameters.

 ./gradlew validateRepresentables

 ./gradlew clean --no-build-cache

> Task :shared:copyFilesToXcode
  > Using xcodeproj gem version 1.27.0 (minimum: 1.27.0)
  > Starting smart sync process
  > KSP output: 4 Swift file(s) found
  > New file: GradientScreenSwiftUIViewControllerRepresentable.swift
  > New file: GradientScreenMixedAUIViewControllerRepresentable.swift
  > New file: GradientScreenMixedBUIViewControllerRepresentable.swift
  > New file: GradientScreenComposeUIViewControllerRepresentable.swift
  > Summary: 0 unchanged, 4 copied, 0 removed
  > Detected changes. Rebuilding Xcode references
  > Created new group "Representables"
  > Adding: GradientScreenComposeUIViewControllerRepresentable.swift
  > Adding: GradientScreenMixedAUIViewControllerRepresentable.swift
  > Adding: GradientScreenMixedBUIViewControllerRepresentable.swift
  > Adding: GradientScreenSwiftUIViewControllerRepresentable.swift
  > Summary: 4 added, 0 removed, 0 unchanged
  > Xcodeproj saved successfully
  > Done

To enable Swift Export support, just follow the official documentation.

When using dependencies from other modules:

swiftExport {
    moduleName = "Shared"
    export(projects.otherModule) { ... }
}

Don't forget to import the plugin in each module. Check the sample-swift-export.

[!IMPORTANT] When switching between modes - embedAndSignAppleFrameworkForXcode to embedSwiftExportForXcode or vice versa - it's recommended to follow this steps:

1. Delete the Derived Data using Xcode or DevCleaner app;
2. Run ./gradlew clean --no-build-cache.

The SPM export mode works with both Swift Export and ObjC Export . It generates a local Swift Package with the generated UIViewControllerRepresentable files, replacing the xcodeproj gem approach. Enable it in the ComposeUiViewController block:

ComposeUiViewController {
    iosAppName = "Gradient"
    targetName = "Gradient"
    experimentalSpmExport = true
}

Run this task once after enabling experimentalSpmExport. It creates the local Swift Package stub and automatically adds the package reference to your Xcode project — no manual Xcode changes needed:

./gradlew :shared:createRepresentablesPackage

After running it, you should see a Swift Package Dependency in your project. The package is empty at this point, but it's ready to be populated with the generated UIViewControllerRepresentable files on every build.

[!NOTE] This task is idempotent: safe to re-run after ./gradlew clean.

To fully remove the generated SPM package and its Xcode project reference (e.g. to reset and start over), run:

./gradlew :shared:deleteRepresentablesPackage

This will remove the Package containing the Representables. Afterward, run createRepresentablesPackage to set it up again.

 ./gradlew validateRepresentables

 ./gradlew clean --no-build-cache

> Task :shared:exportToSpm
  > Arch: iosSimulatorArm64, Config: Debug
  > Swift Export: interfaces linked → iosSimulatorArm64/Debug/dd-interfaces
  > Package.swift updated
  > Starting smart sync process
  > KSP output: 4 Swift file(s) found
  > New file: GradientScreenSwiftUIViewControllerRepresentable.swift
  > New file: GradientScreenMixedAUIViewControllerRepresentable.swift
  > New file: GradientScreenMixedBUIViewControllerRepresentable.swift
  > New file: GradientScreenComposeUIViewControllerRepresentable.swift
  > Summary: 0 unchanged, 4 copied, 0 removed
  > Done

  > Task :shared:exportToSpm
  > Arch: iosSimulatorArm64, Config: Debug
  > ObjC Export: framework linked → Debug/iphonesimulator26.5
  ...

Inside iosMain we can take advantage of two annotations:

@ComposeUIViewController:
To annotate the @Composable as a desired ComposeUIViewController to be used by the iOS app.

@ComposeUIViewControllerState:
To annotate the parameter as the composable state variable (for advanced use cases).

[!IMPORTANT] Only 0 or 1 @ComposeUIViewControllerState and an arbitrary number of parameter types (excluding @Composable) are allowed in @ComposeUIViewController functions.

@ComposeUIViewController
@Composable
internal fun ComposeSimpleView() { }

object ComposeSimpleViewUIViewController {
    fun make(): UIViewController {
        return ComposeUIViewController {
            ComposeSimpleView()
        }
    }
}

import Shared
import SwiftUI

public struct ComposeSimpleViewRepresentable: UIViewControllerRepresentable {
    public init() {}

    public func makeUIViewController(context _: Context) -> UIViewController {
        ComposeSimpleViewUIViewController().make()
    }

    public func updateUIViewController(_: UIViewController, context _: Context) {
        // unused
    }
}

data class ViewState(val isLoading: Boolean)

@ComposeUIViewController
@Composable
internal fun ComposeAdvancedView(@ComposeUIViewControllerState viewState: ViewState, callback: () -> Unit) { }

object ComposeAdvancedViewUIViewController {
    private val viewState = mutableStateOf<ViewState?>(null)

    fun make(callback: () -> Unit): UIViewController {
        return ComposeUIViewController {
            viewState.value?.let { ComposeAdvancedView(it, callback) }
        }
    }

    fun update(viewState: ViewState) {
        this.viewState.value = uiState
    }
}

import Shared
import SwiftUI

public struct ComposeAdvancedViewRepresentable: UIViewControllerRepresentable {
    @Binding public var viewState: ViewState
    public let callback: () -> Void

    public init(viewState: Binding<ViewState>, callback: @escaping () -> Void) {
        self._viewState = viewState
        self.callback = callback
    }

    public func makeUIViewController(context _: Context) -> UIViewController {
        ComposeAdvancedViewUIViewController().make(callback: callback)
    }

    public func updateUIViewController(_: UIViewController, context _: Context) {
        ComposeAdvancedViewUIViewController().update(viewState: viewState)
    }
}

After a successful build the UIViewControllerRepresentable files are included and referenced in the xcodeproj ready to be used:

import SwiftUI
import Shared

struct SomeView: View {
    @State private var state: ViewState = ViewState(isLoading: false)
    var body: some View {
        VStack {
            ComposeSimpleViewRepresentable()
            ComposeAdvancedViewRepresentable(viewState: $state, callback: {})
        }
    }
}

[!IMPORTANT] When not using SPM export mode, always delete iosApp/Representables through Xcode.

For working samples check sample-objc-export, sample-objc-export-spm, sample-swift-export or sample-swift-export-spm. Open iosApp/Gradient.xcodeproj in Xcode and run standard configuration or use KMP plugin for Android Studio and choose Gradient in run configurations.

You'll find different use cases:

• GradientScreenCompose: A screen rendered entirely in Compose (UI+state) and embedded in iOS;
• GradientScreenMixedA: A screen rendered entirely in Compose with its state controlled by iOS;
• GradientScreenMixedB: A screen rendered in Compose with a SwiftUI View embedded in it, and the state controlled by iOS;
• GradientScreenSwift: A screen rendered entirely in Swift (UI+state) and embedded in Compose.

You can also find other working samples in:

Copyright (c) 2023-present GuilhE

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.