Koin Migration from KSP to Compiler Plugin

https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin
Admin
Migration guide for transitioning Koin Annotations projects from KSP-based processing to the new...
Tokens:2,916
Snippets:39
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### KSP Koin Startup (JVM)

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Example of Koin startup code using generated extensions from KSP.

```kotlin
import org.koin.ksp.generated.*

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

fun main() {
    startKoin {
        modules(AppModule().module)  // Generated .module extension
    }
}

```

--------------------------------

### KSP Build Configuration

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Example of build.gradle.kts configuration using KSP for Koin Annotations.

```gradle
plugins {
    alias(libs.plugins.ksp)
}

dependencies {
    implementation(libs.koin.core)
    implementation(libs.koin.annotations)  // KSP version (separate versioning)  
    ksp(libs.koin.ksp.compiler)
}

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

```

--------------------------------

### KSP Version Catalog

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Example version catalog configuration for KSP-based Koin Annotations.

```gradle
[versions]
koin = "4.0.0"
koin-ksp = "2.0.0"  # Separate versioning for KSP annotations  
ksp = "2.0.0-1.0.22"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin-ksp" }
koin-ksp-compiler = { module = "io.insert-koin:koin-ksp-compiler", version.ref = "koin-ksp" }

[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }

```

--------------------------------

### KSP Koin Startup (Android)

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Example of Android Koin startup code using generated extensions from KSP.

```kotlin
import org.koin.ksp.generated.

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidContext(this@MyApplication)
            modules(AppModule().module)
        }
    }
}

```

--------------------------------

### Simplify KMP Setup with Compiler Plugin

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Migrate Kotlin Multiplatform (KMP) projects from KSP to the Compiler Plugin by applying a single plugin and adjusting dependency declarations. This eliminates the need for per-platform KSP compiler dependencies.

```kotlin
// shared/build.gradle.kts  
plugins {  
    kotlin("multiplatform")  
    id("com.google.devtools.ksp")  
}  
  
kotlin {  
    sourceSets {  
        commonMain.dependencies {  
            implementation("io.insert-koin:koin-core:$koin_version")  
            implementation("io.insert-koin:koin-annotations:$koin_ksp_version")  // Separate version  
        }  
    }  
}  
  
dependencies {  
    // KSP compiler required for each platform  
    add("kspAndroid", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")  
    add("kspIosX64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")  
    add("kspIosArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")  
    add("kspIosSimulatorArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")  
}  
```

```kotlin
// shared/build.gradle.kts  
plugins {  
    kotlin("multiplatform")  
    alias(libs.plugins.koin.compiler)  
}  
  
kotlin {  
    sourceSets {  
        commonMain.dependencies {  
            implementation(libs.koin.core)  
            implementation(libs.koin.annotations)  
        }  
    }  
}  
```

--------------------------------

### Migrate Koin DSL Syntax to Compiler Plugin Style

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Update Koin DSL module definitions to use the Compiler Plugin's cleaner syntax. This involves changing from 'singleOf(::MyService)' to 'single<MyService>()' and similar transformations for factory, viewModel, scoped, and worker definitions. The example also shows how to use function builders for external libraries like Room.

```kotlin
// Before  
val myModule = module {  
    singleOf(::MyService)  
    factoryOf(::MyRepository)  
    viewModelOf(::MyViewModel)  
}  
  
// After  
import org.koin.plugin.module.dsl.*  
  
val myModule = module {  
    single<MyService>()  
    factory<MyRepository>()  
    viewModel<MyViewModel>()  
}  
  
// Function builders — for external libraries (Room, Retrofit, etc.)  
fun createDatabase(context: Context): AppDatabase =  
    Room.databaseBuilder(context, AppDatabase::class.java, "db").build()  
  
val dbModule = module {  
    single { create(::createDatabase) }  
}  
```

--------------------------------

### Update Koin Startup Code (JVM)

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Migrate Koin startup from generated extensions to the typed API using @KoinApplication.

```kotlin
// No generated imports needed

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

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

fun main() {
    startKoin<MyApp>()  // Typed API
}

```

--------------------------------

### Update Koin Startup Code (Android)

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Adapt Android Koin startup for the Compiler Plugin, using the typed API.

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

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin<MyApp> {
            androidContext(this@MyApplication)
        }
    }
}

```

--------------------------------

### Configure Cross-Module Discovery with @Configuration

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Use the @Configuration annotation in feature modules to enable automatic discovery by the main application module, which uses @KoinApplication and startKoin. This simplifies dependency injection across different Gradle modules.

```kotlin
// In feature module  
@Module  
@ComponentScan  
@Configuration  
class FeatureModule  
  
// In app module - FeatureModule is auto-discovered  
@KoinApplication  
object MyApp  
  
startKoin<MyApp>()  // FeatureModule automatically included  
```

--------------------------------

### Update Build Configuration for Koin Compiler Plugin

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Replace the KSP plugin with the Koin Compiler Plugin and adjust dependencies.

```gradle
plugins {
    alias(libs.plugins.koin.compiler)
}

dependencies {
    implementation(libs.koin.core)
    implementation(libs.koin.annotations)  // Same version as koin-core
}

// Optional configuration
koinCompiler {
    userLogs = true  // Log component detection
}

```

--------------------------------

### Update Version Catalog for Koin Compiler Plugin

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Modify your version catalog to use the new Koin plugin and versioning scheme.

```gradle
[versions]
koin = "4.2.0"
koin-plugin = "1.0.0"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }

```

--------------------------------

### Enable Compiler Plugin Logging

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Enable verbose logging for the Koin Compiler Plugin by setting 'userLogs = true' in the build script to help diagnose issues with annotation detection.

```kotlin
koinCompiler {  
    userLogs = true  
}  
```

--------------------------------

### Koin Annotations Remain Unchanged

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Illustrates that Koin annotations like @Singleton, @Factory, @KoinViewModel, and @Module do not require modification.

```kotlin
// No changes needed!  
@Singleton  
class UserRepository(private val database: Database)

@Factory  
class GetUserUseCase(private val repository: UserRepository)

@KoinViewModel  
class UserViewModel(private val useCase: GetUserUseCase) : ViewModel()

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

```

--------------------------------

### Define Top-Level Functions for Dependency Injection

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Use top-level functions annotated with DI scopes like @Singleton or @Factory for dependency definitions. The Compiler Plugin discovers these via @ComponentScan. Function return types determine the binding type, and parameters are injected as dependencies.

```kotlin
@Singleton  
fun provideDatabase(): DatabaseService = PostgresDatabase()  
  
@Factory  
fun provideCache(db: DatabaseService): CacheService = RedisCache(db)  
  
@Module  
@ComponentScan("com.myapp")  
class AppModule  
```

--------------------------------

### Clean Up KSP Generated Files

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Remove old KSP-generated files and perform a clean build after migration.

```bash
rm -rf build/generated/ksp
./gradlew clean build

```

--------------------------------

### Update @KoinViewModel Import

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Change the import path for the @KoinViewModel annotation when migrating from KSP to the Compiler Plugin.

```kotlin
// Before (KSP)  
import org.koin.android.annotation.KoinViewModel  
  
// After (Compiler Plugin)  
import org.koin.core.annotation.KoinViewModel  
```

--------------------------------

### Update Kotlin Version for Koin Compiler Plugin

Source: https://insert-koin.io/docs/migration/from-ksp-to-compiler-plugin

Ensure your project uses Kotlin 2.3.20 or higher, as required by the Koin Compiler Plugin.

```kotlin
plugins {
    kotlin("jvm") version "2.3.20" // 2.3.20 minimum
}

```
Tokens:
Raw