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 * { *; }