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​