koin-kmp
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-10-14
- Stars
- ★ 0
- Forks
- 0
02 资源文件 1
- 参考文档manifest.yaml1.0 KB
03 SKILL.md 正文
Koin for KMP Skill
Koin wiring in a Kotlin Multiplatform project: what belongs in commonMain versus behind
expect val platformModule: Module, obtaining a ViewModel in a Compose Multiplatform screen, scopes,
Classic DSL versus KSP annotations, and turning a missing binding into a failing test rather than a
runtime crash.
Layer boundaries and the dependency direction are normative — see .claude/rules/kmp/architecture.md
and .claude/rules/kmp/modularization.md. This skill wires against those rules; it does not restate
them.
Supersedes dependency-injection-architecture in KMP projects
dependency-injection-architecture is gated requires: [kotlin], so it installs here too, but three
of its Always-Active Rules are backend-specific and wrong for KMP. In a KMP project this skill
wins on exactly these points:
dependency-injection-architecture says |
In a KMP project |
|---|---|
Dependency direction is presentation → domain ← data |
ui → domain ← data — see .claude/rules/kmp/architecture.md |
Only data/db/DatabaseFactory.kt may use Dispatchers.IO |
there is no such file, and Dispatchers.IO does not exist on native or wasm. Inject a CoroutineDispatcher |
Use Service, never UseCase |
the KMP layer rules name the domain orchestration class UseCase |
Everything else it says — constructor injection over by inject(), interface types for bindings,
never inject the container, CoroutineExceptionHandler as its own keyed dependency — still holds.
Scope
In scope
- Module layout across source sets;
expect val platformModule: Moduleand itsactuals. - Binding platform-typed dependencies (HTTP engine,
Context, settings/keychain backing). - Obtaining a ViewModel or a service inside a
@Composable. - Scopes and when a scope is the wrong tool.
- Classic DSL versus
koin-annotations+ KSP, and the generated-module accessor. checkModules()/verify()as a test.- Diagnosing
NoDefinitionFoundExceptionand "compiles but fails at the call site".
Out of scope — hand off, do not answer here
- Which layer a class belongs to →
.claude/rules/kmp/architecture.md - Visibility of a DI-bound implementation →
.claude/rules/kmp/modularization.md - Building the
HttpClientthat gets bound →ktor-client-kmp - Choosing and configuring the storage that gets bound →
kmp-persistence - Source-set mechanics and
expect/actualin general →kmp-multiplatform-specialist - Writing the tests →
kmp-testing - Backend (JVM-only, Exposed/Ktor-server) DI →
dependency-injection-architecture
Procedure
- Read the build files first.
gradle/libs.versions.tomland the module'sbuild.gradle.kts— report the Koin version and whichkoin-*artifacts are actually on the classpath. This is not optional: half of the failures below are a missing artifact, not wrong code. - Find the existing modules (
di/package,initKoin/startKoincall site) and the current style. Do not introduce a second style. - Add the binding at the lowest layer that owns the type,
internalunless another module consumes it. - Verify. Run the module-verification test (below). A binding added without it is unproven.
Source-set layout
Most bindings are platform-free and belong in commonMain. Only genuinely platform-typed ones go
behind the platform module:
// commonMain
expect val platformModule: Module
val appModule = module {
single { createHttpClient(get(), BASE_URL) }
singleOf(::UserRepositoryImpl) bind UserRepository::class
factoryOf(::LoadUserUseCase)
viewModelOf(::UserViewModel)
}
// androidMain
actual val platformModule = module {
single<HttpClientEngine> { OkHttp.create() }
single<CoroutineDispatcher> { Dispatchers.IO }
}
// iosMain
actual val platformModule = module {
single<HttpClientEngine> { Darwin.create() }
single<CoroutineDispatcher> { Dispatchers.Default } // no Dispatchers.IO on native
}
The dispatcher binding is the KMP-specific one: Dispatchers.IO exists only on JVM/Android, so a
class that hardcodes it does not compile for native or wasm. Bind it per platform and inject it.
iOS startup. Swift reserves init, so the shared entry point is normally named doInitKoin and
called from iOSApp.init() as InitKoinKt.doInitKoin(config: nil).
Unverified — no consumer project here declares an iOS target; the iOS lines above are adapted from
rcosteira79/android-skills→koin/SKILL.md.
Compose: koinViewModel, not koinInject
koinInject<T>() resolves through the ordinary graph and returns a single/factory instance. Used
for a ViewModel it produces one with no ViewModelStoreOwner: it is not scoped to the navigation
entry, onCleared() never runs at the right moment, and a single binding makes the "ViewModel"
outlive the screen entirely, carrying stale state back on re-entry.
// wrong — no ViewModel store, no lifecycle
val viewModel: UserViewModel = koinInject()
// right — scoped to the nav entry
val viewModel: UserViewModel = koinViewModel()
val detail: DetailViewModel = koinViewModel { parametersOf(userId) }
koinViewModel lives in koin-compose-viewmodel (KMP) or koin-androidx-compose (Android-only).
koin-core and koin-compose alone do not provide it — which is why a project missing that artifact
"has to" use koinInject. That is a missing dependency, not a style choice: add the artifact.
Without the right artifact koinViewModel fails at the call site rather than at compile time.
For plain services, defaulting the parameter keeps the composable testable:
@Composable
fun UserScreen(analytics: AnalyticsService = koinInject()) { … }
Classic DSL vs KSP annotations
Pick one per module; mixing inside a single module is what breaks. The accessor most often missed is
that @Module @ComponentScan class UserModule is passed as UserModule().module:
@Single class UserRepositoryImpl(private val service: UserService) : UserRepository
@Factory class UserFormValidator
@KoinViewModel class UserDetailViewModel(
@InjectedParam private val userId: String,
private val repository: UserRepository,
) : ViewModel()
@Module @ComponentScan("com.example.feature.user") class UserModule
// startKoin { modules(UserModule().module) }
Annotations need koin-annotations + the koin-ksp-compiler wired per target. Classic DSL needs no
codegen and stays readable in a small graph — prefer it unless the module is large enough that the
boilerplate is the actual problem.
Scopes
A scope is for state with a lifetime between "one call" and "the whole app" — a multi-step flow keyed by an id, for example. Own it explicitly and close it:
val scope = getKoin().createScope<CheckoutFlow>("checkout-$orderId")
val cart: CheckoutCart = scope.get()
// …
scope.close()
A scope that is never closed is a leak that no test catches. If the lifetime you want is "this
screen", that is what koinViewModel already gives you — use it instead.
Verification as a test
checkModules() walks every declaration's constructor and fails when a dependency is not declared,
turning a runtime NoDefinitionFoundException into a red test.
// commonTest
class ModuleVerificationTest {
@Test
fun should_resolve_every_declaration() {
koinApplication { modules(appModule, platformModule) }.checkModules()
}
}
For constructor parameters supplied at runtime (SavedStateHandle, a parametersOf value), declare
them with verify(extraTypes = listOf(SavedStateHandle::class)) — otherwise verification fails on a
binding that is actually correct.
Do NOT
- Do NOT use
koinInject()for a ViewModel — usekoinViewModel()and add the artifact. - Do NOT bind a ViewModel as
single; it then survives navigation with stale state. - Do NOT hardcode
Dispatchers.IOinside a class — it does not exist on native/wasm. Inject it. - Do NOT put a platform type in
commonMainbindings; that is whatplatformModuleis for. - Do NOT inject
Koin,ScopeorKoinComponentinto a class — that is the service-locator anti-pattern back in disguise. - Do NOT mix Classic DSL and annotations inside one module.
- Do NOT widen a binding's implementation class to
publicjust to declare it — declarations seeinternaltypes within the same module. - Do NOT create a scope you have no code path to close.
Error handling
NoDefinitionFoundExceptionat runtime → the graph is unverified. AddcheckModules()first, then fix the binding it names.koinViewModelunresolved or failing at the call site → report the missing artifact (koin-compose-viewmodel) and its catalog entry; do not work around it withkoinInject.checkModules()fails on a runtime-supplied parameter → addextraTypes; do not delete the test.- An
actual platformModuleis missing for a declared target → name the target and the missing bindings, and hand source-set mechanics tokmp-multiplatform-specialist. - The question is about layering, not wiring → point at
.claude/rules/kmp/architecture.mdand stop.
Example
"Add a settings screen backed by a repository that reads from encrypted storage."
- Read
libs.versions.toml; report the Koin version and whetherkoin-compose-viewmodelis present. If it is not, propose the catalog entry before writing any Compose code. - Bind the storage in
platformModuleper target (encrypted on Android, keychain on iOS, plain on Desktop) — the choice itself belongs tokmp-persistence. - Bind
SettingsRepositoryImplasinternalbehind thepublicSettingsRepositoryinterface incommonMain. - Declare
viewModelOf(::SettingsViewModel)and obtain it in the screen withkoinViewModel(). - Extend the module-verification test to include the new module; run it and report the output.
Expected outcome: the graph verifies in commonTest, and no platform type appears in commonMain.
Related Skills
kmp-multiplatform-specialist— source sets,expect/actual, targetsktor-client-kmp— the client and engine that get boundkmp-persistence— choosing the storage behind the bindingkmp-testing— fakes,commonTestplacement, overriding bindings in testskotlin-specialist— dispatchers, scopes,CoroutineExceptionHandlerdependency-injection-architecture— the backend (JVM-only) counterpart
04 同仓库更多 Skills
universal-skill
暂无简介
notion-skill
暂无简介
inline-frontmatter-skill
Hand-authored description that already lives in the body and must not be double-wrapped.
universal-skill
暂无简介
notion-skill
暂无简介
write-a-skill
暂无简介