Skip to main content
Version: 4.2

Koin Compiler Plugin Setup

The Koin Compiler Plugin is the recommended approach for all new Kotlin 2.x projects. It provides auto-wiring, compile-time safety, and a cleaner DSL syntax.

What is the Compiler Plugin?​

The Koin Compiler Plugin is a native Kotlin Compiler Plugin (K2) that:

  • Auto-detects constructor dependencies
  • Provides compile-time analysis
  • Works with both DSL and Annotations
  • Generates no visible files

See Introduction to Koin Compiler Plugin for details on features and benefits.

Requirements​

  • Kotlin 2.x (K2 compiler)
  • Gradle 8.x+

Setup​

Step 1: Add the Plugin to Settings​

In your settings.gradle.kts:

pluginManagement {
plugins {
id("io.insert-koin.compiler.plugin") version "1.0.0" apply false
}
}

Or using plugin resolution:

pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
}
}

Step 2: Apply the Plugin​

In your module's build.gradle.kts:

plugins {
id("io.insert-koin.compiler.plugin")
}

Step 3: Add Koin Dependencies​

dependencies {
implementation(platform("io.insert-koin:koin-bom:4.2.0"))
implementation("io.insert-koin:koin-android") // or your platform
}

Complete Example​

settings.gradle.kts​

pluginManagement {
plugins {
id("io.insert-koin.compiler.plugin") version "1.0.0" apply false
}
}

dependencyResolutionManagement {
repositories {
mavenCentral()
google()
}
}

app/build.gradle.kts​

plugins {
id("com.android.application")
id("org.jetbrains.kotlin.android")
id("io.insert-koin.compiler.plugin")
}

dependencies {
implementation(platform("io.insert-koin:koin-bom:4.2.0"))
implementation("io.insert-koin:koin-android")
implementation("io.insert-koin:koin-androidx-compose")
}

Using the Compiler Plugin​

DSL Style​

Import from the compiler plugin package:

import org.koin.plugin.module.dsl.*
import org.koin.dsl.module

val appModule = module {
single<Database>()
single<ApiClient>()
single<UserRepository>()
viewModel<UserViewModel>()
}
note

The Compiler Plugin DSL is in package org.koin.plugin.module.dsl. Classic DSL remains in org.koin.dsl.

Annotation Style​

Use annotations on your classes:

@Singleton
class Database

@Singleton
class ApiClient

@Singleton
class UserRepository(
private val database: Database,
private val apiClient: ApiClient
)

@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()

@Module
@ComponentScan("com.myapp")
class AppModule

Then use the generated module:

import org.koin.ksp.generated.*

startKoin {
modules(AppModule().module)
}

Or with configuration-based auto-discovery:

@Module
@ComponentScan("com.myapp")
@Configuration // Auto-discovered
class AppModule

// In your app
@KoinApplication
object MyApp

fun main() {
MyApp.startKoin()
}

Configuration Options​

Configure the compiler plugin in your build.gradle.kts:

koinCompiler {
// Configuration options
}

Available Options​

OptionDescriptionDefault
configCheckEnable compile-time configuration validationfalse

Example:

koinCompiler {
configCheck = true
}
info

More configuration options are planned for future releases.

Multi-Module Projects​

For projects with multiple Gradle modules:

Library Module​

// feature/build.gradle.kts
plugins {
id("io.insert-koin.compiler.plugin")
}

dependencies {
implementation(platform("io.insert-koin:koin-bom:4.2.0"))
implementation("io.insert-koin:koin-core")
}
// feature/src/main/kotlin/FeatureModule.kt
@Module
@ComponentScan("com.myapp.feature")
@Configuration // Auto-discovered by app module
class FeatureModule

App Module​

// app/build.gradle.kts
plugins {
id("io.insert-koin.compiler.plugin")
}

dependencies {
implementation(project(":feature"))
implementation(platform("io.insert-koin:koin-bom:4.2.0"))
implementation("io.insert-koin:koin-android")
}
// app/src/main/kotlin/MyApp.kt
@KoinApplication
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
startKoin()
}
}

With @Configuration on your modules, they're automatically discovered.

Kotlin Multiplatform​

The Compiler Plugin works with KMP projects:

// shared/build.gradle.kts
plugins {
id("org.jetbrains.kotlin.multiplatform")
id("io.insert-koin.compiler.plugin")
}

kotlin {
sourceSets {
commonMain.dependencies {
implementation(platform("io.insert-koin:koin-bom:4.2.0"))
implementation("io.insert-koin:koin-core")
}
}
}

Troubleshooting​

Plugin Not Found​

Ensure the plugin is in your plugin repositories:

// settings.gradle.kts
pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
}
}

Kotlin Version Mismatch​

The Compiler Plugin requires Kotlin 2.x. Check your Kotlin version:

// build.gradle.kts
plugins {
kotlin("jvm") version "2.0.0" // Requires 2.x
}

Import Errors​

Make sure you're importing from the correct package:

// Compiler Plugin DSL
import org.koin.plugin.module.dsl.*

// Classic DSL
import org.koin.dsl.*

Generated Code Not Found​

For annotations, ensure you're importing the generated extensions:

import org.koin.ksp.generated.*

Migration​

From Classic DSL​

  1. Add the Compiler Plugin
  2. Update imports to org.koin.plugin.module.dsl.*
  3. Replace singleOf(::Class) with single<Class>()

See Migrating from DSL to Compiler Plugin.

From KSP Annotations​

  1. Remove KSP plugin and dependencies
  2. Add Koin Compiler Plugin
  3. Your annotations stay the same!

See Migrating from KSP to Compiler Plugin.

Next Steps​