koin Documentation

Koin

Koin is the pragmatic dependency injection framework for Kotlin and Kotlin Multiplatform (Android, iOS, desktop, web, Ktor server). Two styles, one container: Koin DSL or Koin Annotations (JSR-330 compatible). Compile safe in both styles with the Koin Compiler Plugin — no KSP, no kapt, no generated files. Current versions: Koin 4.2.2, Koin Compiler Plugin 1.2.1, Kotlin 2.3.20 or later.

Key facts for writing Koin code:

• Pick one style per project and state it — don't mix DSL and Annotations unless asked (then one style per module).
  • Koin DSL keeps DI out of the code: classes carry no annotations, wiring lives in module { } files. Three forms:
    • Compiler Plugin DSL single<T>() / single { create(::buildT) } — recommended with the Compiler Plugin.
    • Constructor DSL singleOf(::T) — projects without the Compiler Plugin.
    • Classic DSL single { T(get()) } — custom expressions only.
  • Koin Annotations @Singleton, @Factory, @KoinViewModel, @Module — the Hilt / Dagger model, JSR-330 compatible (@Inject, @Singleton, @Named, @Qualifier). Prefer @Singleton over @Single.
• Koin Compiler Plugin (id("io.insert-koin.compiler.plugin")) checks the whole graph at build time, DSL and Annotations alike. It replaces checkModules() / verify() tests.
• Koin KSP is deprecated — never add koin-ksp-compiler, never import org.koin.ksp.generated.*, never pin koin-annotations:2.x. Let koin-bom resolve versions.
• Compiler Plugin DSL primitives and startKoin<App> live in org.koin.plugin.module.dsl.
• Runtime behavior (graph behavior, scopes, memory, performance) is not checked by the compiler: use the Kotzilla MCP.

Docs Copy Chapter

• What is Koin: positioning and core concepts
• Koin Compiler Plugin: compile-time safety for DSL and Annotations
• Setup: Gradle, BOM and artifacts per platform
• Compiler Plugin setup: plugin id, version catalog, options
• Koin Annotations tutorial: Annotations with the Compiler Plugin
• Choosing your style: Compiler Plugin DSL, Constructor DSL, Classic DSL or Annotations
• Koin DSL: modules and definitions
• Compile-time safety: what the plugin verifies
• Modules: includes(), @Configuration, @ComponentScan
• Start Koin: startKoin, properties, module loading
• Scopes: scoped definitions and lifecycles
• KMP shared modules: common and platform modules
• Compose: koinViewModel(), koinInject()
• Testing: koin-test, JUnit 4 / 5
• Koin vs Hilt / Dagger: comparison and migration

AI tooling Copy Chapter

• Koin skills: official agent skills to set up Koin, write Koin code, migrate from Hilt / Dagger / Toothpick / Kodein / Metro / Koin KSP / Koin 3.x, and diagnose Koin apps. Claude Code: /plugin marketplace add InsertKoinIO/koin-skills then /plugin install koin@koin-skills
• Kotzilla MCP: Koin knowledge, Koin error diagnosis, and runtime debugging (graph behavior, scopes, memory, performance). Claude Code: claude mcp add kotzilla --transport http https://mcp.kotzilla.io/mcp

Repository Copy Chapter

• AGENTS.md: building, testing and contributing to this repository
• Koin Compiler Plugin repository: compiler plugin sources
• Koin IDE plugin: IntelliJ IDEA / Android Studio navigation and inspections

Optional Copy Chapter

• API cheat sheet: code samples for every Koin API (definitions, scopes, ViewModel, WorkManager, qualifiers, Ktor)
• Kotzilla: observability platform for Koin and KMP apps