The Structure of a Kotlin Multiplatform iPhone App

​

What does the tree look like?

src-kmp/
└── apple-umbrella/             # builds the Kotlin core as <Project>Kit.xcframework
src-ios/
├── App/
│   ├── xcodegen.yml            # the Xcode project spec; the .xcodeproj is generated
│   ├── xcconfig/               # Debug, AdHoc and AppStore build settings
│   ├── <Project>/              # the app target: AppDelegate, SceneDelegate, SceneComponent
│   └── <Project>Widgets/       # a WidgetKit extension
├── Libraries/
│   ├── <Project>Kit/           # the binary target over the XCFramework, and the bridge
│   ├── <Project>Main/          # the composition root, shells, views, workers
│   ├── Theming/                # the theme and its design tokens
│   ├── WidgetShared/           # data the app and the widget extension share
│   └── MemoryLaneConnector/    # a generated backend client
└── Subtrees/
    └── Priming/PrimingNode/    # one feature's iOS shell as its own package
scripts/
└── assemble_kit.sh             # assembles the core; every iOS build runs it first
parity/fixtures/                # the recordings the Kotlin and Swift lanes replay

​

What is in the Kit package?

.binaryTarget(
  name: "<Project>Kit",
  path: "../../../src-kmp/apple-umbrella/build/XCFrameworks/app/<Project>Kit.xcframework"
),
.target(
  name: "<Project>Bridge",
  dependencies: [
    .target(name: "<Project>Kit"),
    .product(name: "DuetShells", package: "duet"),
  ],
  linkerSettings: [
    .linkedLibrary("c++"),
    .linkedFramework("Foundation"),
  ]
),

• The binary target is a build product of the project’s own Kotlin sources. build/ is not committed, so a fresh clone has no framework until the first assemble; How do you build it? covers when that happens.
• The bridge holds BridgedStore, the one class every shell uses to hold a Kotlin store: a @Published mirror of the store’s state, a synchronous send, and a cancel() that stops the Kotlin runtime. Tutorial 2 writes it.
• The shells. The scaffold emits each feature’s iOS side into this package as a <Feature>Shell target: a Builder that makes the Kotlin store and the bridged mirror, a ViewShell that turns intents into actions and state into view state, the SwiftUI view, and a spec target that tests the shell. Memory Lane keeps its 14 shell directories in the Main package’s Shells/ instead; both layouts depend on the same bridge.

​

What is in the Main package?

• The composition root. RootBuilder builds the root level: a RootComponent that owns the app-lifetime services (diagnostics, analytics, the inbound URL and push registry), adopts them as workers in a StoreHost, and then mounts the features. Composition is a Dependency, a Component and a Builder per level, the same three parts the Android app uses (Tutorial 3).
• Mounts. The scaffold writes one Features/<Feature>Mount.swift per feature: a function that calls the feature’s Builder, wraps the view in a MountedFeature, and gives the scene the mount’s activate and deactivate bracket. A child’s delegate events are routed in that file’s onDelegate closure.
• The root screen. RootScreen renders the mounted features. As emitted it shows one feature full-screen, with a tab strip once there are two; the app’s real navigation replaces it as the product grows.
• Workers. Everything that touches the world, implemented in Swift behind the ports the Kotlin reducers name as effects. Memory Lane’s Workers/ has 21 of them: repository workers over its backend, push notifications, media storage, image downscaling, video transcoding, widget sync.

​

Where do the theme and the controls live?

• Libraries/Theming/ holds the app’s theme. Its semantic colors, fonts and gradients are generated by duet design-tokens from parity/design-tokens.yaml, the file the Android theme is generated from too, so both apps read the same token names. A hand edit to a generated file fails duet design-tokens --check.
• Libraries/ThemedControls/ holds the shared controls built on the theme. The scaffold emits AppButton, the one action-button style every screen uses, with primary, secondary and destructive roles. Memory Lane keeps its button, MLButton, in the Theming package.

​

What is in the app target?

• SceneDelegate builds the root with RootBuilder(dependency: SceneComponent()).build(), puts RootScreen in a UIHostingController inside the theme’s scope, calls activate(), and calls teardown() when the scene disconnects. In Memory Lane it also forwards every opened URL to the app-services registry the root returned.
• SceneComponent is the root level’s Dependency: the objects only the scene can supply. As emitted it is empty.
• AppDelegate carries process-level duties; in Memory Lane, the launch services and the push-notification device token.

1. Increment BUILD_NUMBER, for builds other than Debug.
2. Assemble the Kotlin core: scripts/assemble_kit.sh debug for a Debug build and release otherwise, so the build links the framework that contains the latest Kotlin edit.

​

How do you build it?

scripts/assemble_kit.sh debug
(cd src-ios/App && xcodegen generate --spec xcodegen.yml)
open src-ios/App/<Project>.xcodeproj

​

What does day one look like?

• <Project>Kit with the binary target and <Project>Bridge;
• <Project>Main with RootComposition.swift (the root’s Dependency, Component and Builder), RootScreen.swift, the analytics and ingress workers, and a test target;
• Theming and ThemedControls;
• the app target with its three entry files and the scheme’s pre-actions.

​

Common questions

​

Sources and further reading

• Kotlin Multiplatform: build final native binaries: binaries.framework and XCFramework, the Gradle side of the Kit package’s binary target
• Swift Package Manager: binary targets: how a package declares a prebuilt XCFramework
• XcodeGen: the project spec format xcodegen.yml uses
• WidgetKit: the extension type Memory Lane’s widgets use
• The Duet framework on GitHub: DuetShells (ViewShell, StoreHost) and the toolchain

​

Read next