Skip to main content
Version: 4.2

Starting with Koin Annotations

Koin Annotations status

Koin Annotations is now part of the Koin project. The koin-annotations library ships under the main Koin version and is fully supported.

The legacy KSP processor (koin-ksp-compiler) is deprecated in favor of the Koin Compiler Plugin — your annotations stay the same; only the build setup changes. See Migrating from KSP to Compiler Plugin.

Koin Annotations let you declare definitions using annotations on your classes. The Koin Compiler Plugin processes these annotations and generates all underlying Koin DSL for you at compile time.

Getting Started​

Not familiar with Koin? First, take a look at Koin Getting Started

Setup​

Add the Koin Compiler Plugin to your project. See Compiler Plugin Setup for complete instructions.

// build.gradle.kts
plugins {
    alias(libs.plugins.koin.compiler)
}

dependencies {
    implementation(libs.koin.core)
    implementation(libs.koin.annotations)
}

Annotating Components​

Tag your components with definition annotations:

@Singleton
class MyRepository

@Singleton
class MyService(val repository: MyRepository)

@Factory
class MyUseCase(val service: MyService)

Declaring Modules​

Create a module to organize your definitions:

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

Starting Koin​

Use @KoinApplication with the typed startup API:

@KoinApplication(modules = [AppModule::class])
class MyApp

fun main() {
    startKoin<MyApp> {
        printLogger()
    }

    // Use your Koin API as usual
    KoinPlatform.getKoin().get<MyService>()
}

Configuration Labels​

Use @Configuration to create modules that load based on labels:

@Module
@Configuration  // Default configuration
class CoreModule

@Module
@Configuration("prod")
class ProdModule

@Module
@Configuration("test")
class TestModule

Load specific configurations:

@KoinApplication(
    modules = [CoreModule::class],
    configurations = ["prod"]  // Only loads @Configuration("prod") modules
)
class ProdApp

fun main() {
    startKoin<ProdApp>()
}

Typed Startup APIs​

The Compiler Plugin provides typed APIs for starting Koin:

APIDescription
startKoin<T>()Start Koin globally
startKoin<T> { }Start with configuration block
koinApplication<T>()Create isolated KoinApplication
koinConfiguration<T>()Create configuration (for Compose, Ktor)
module<T>()Load a single @Module class
modules(A::class, B::class)Load multiple @Module classes

Where T is a class annotated with @KoinApplication (for startup APIs) or @Module (for module loading APIs).

Loading Individual Modules​

You can load @Module classes directly without @KoinApplication:

startKoin {
    module<NetworkModule>()
    modules(DataModule::class, CacheModule::class)
}

This is especially useful for tests:

@get:Rule
val koinTestRule = KoinTestRule.create {
    module<NetworkModule>()
}

Compile-Time Safety​

The Compiler Plugin verifies your Koin configuration at compile time, checking that all dependencies are declared and accessible.

Bypass with @Provided​

Use @Provided to indicate a dependency is provided externally:

class ExternalComponent  // Declared elsewhere

@Factory
class MyPresenter(@Provided val external: ExternalComponent)

Compiler Plugin Options​

See Compiler Plugin Options for all configuration options.

ProGuard Rules​

For SDK development with ProGuard/R8:

# Keep annotation definitions
-keep class org.koin.core.annotation.** { *; }

# Keep classes annotated with Koin annotations
-keep @org.koin.core.annotation.* class * { *; }

See Also​