Skip to main content
Version: 4.1

Starting with Koin Annotations

The goal of Koin Annotations project is to help declare Koin definition in a very fast and intuitive way, and generate all underlying Koin DSL for you. The goal is to help developer experience to scale and go fast 🚀, thanks to Kotlin Compilers.

Getting Started​

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

Tag your components with definition & module annotations, and use the regular Koin API.

// Tag your component to declare a definition
@Single
class MyComponent
// Declare a module and scan for annotations
@Module
@ComponentScan
class MyModule

Use the org.koin.ksp.generated.* import as follows to be able to use generated code:

// Use Koin Generation
import org.koin.ksp.generated.*

fun main() {
val koin = startKoin {
printLogger()
modules(
// use your modules here, with generated ".module" extension on Module classes
MyModule().module
)
}

// Just use your Koin API as regular
koin.get<MyComponent>()
}

That's it, you can use your new definitions in Koin with the regular Koin API

KSP Options​

The Koin compiler offers some options to configure. Following the official doc, you can add the following options to your project: Ksp Quickstart Doc

Compile Safety - check your Koin config at compile time (since 1.3.0)​

Koin Annotations allows the compiler plugin to verify your Koin configuration at compile time. This can be activated with the following Ksp options, to add to your Gradle module:

// in build.gradle or build.gradle.kts

ksp {
arg("KOIN_CONFIG_CHECK","true")
}

The compiler will check that all dependencies used in your configuration are declared, and all used modules are accessible.

Bypass Compile Safety with @Provided (since 1.4.0)​

Among the ignored types from the Compiler (Android common types), the compiler plugin can verify your Koin configuration at compile time. If you want to exclude a parameter from being checked, you can use @Provided on a parameter to indicate that this type is provided externally to the current Koin Annotations config.

The following indicates that MyProvidedComponent is already declared in Koin:

class MyProvidedComponent

@Factory
class MyPresenter(@Provided val provided : MyProvidedComponent)

Disabling Default Module (since 1.3.0)​

By default, the Koin compiler detects any definition not bound to a module and puts it in a "default module", a Koin module generated at the root of your project. You can disable the use and generation of the default module with the following option:

// in build.gradle or build.gradle.kts

ksp {
arg("KOIN_DEFAULT_MODULE","false")
}

Kotlin KMP Setup​

Please follow the KSP setup as described in the official documentation: KSP with Kotlin Multiplatform

You can also check the Hello Koin KMP project with a basic setup for Koin Annotations.

Pro-Guard​

If you intend to embed the Koin Annotations application as an SDK, take a look at those pro-guard rules:

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

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