KSP Annotations Setup

warning

Deprecated: The KSP-based annotation processing approach is deprecated. Please migrate to the Koin Compiler Plugin for all new projects.

Your annotations stay the same - only the build setup changes. See Migration Guide below.

Why Migrate?

Aspect	KSP Annotations	Compiler Plugin
Generated files	Visible in build/	None
Build speed	Slower	Faster
KMP setup	Complex	Simple
Future support	⚠️ Deprecated	✅ Active development
Your code	Same	Same

When to Use KSP (Temporary)

Only use KSP if you're:

• Stuck on Kotlin 1.x (upgrade recommended)
• Mid-migration and can't switch yet
• Have specific KSP requirements

Current KSP Setup (Reference)

If you must use KSP, here's the setup:

Gradle Setup

// build.gradle.kts
plugins {
    id("com.google.devtools.ksp") version "$ksp_version"
}

dependencies {
    implementation(platform("io.insert-koin:koin-bom:$koin_version"))
    implementation("io.insert-koin:koin-core")
    implementation("io.insert-koin:koin-annotations:$koin_ksp_version")
    ksp("io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
}

Version Compatibility

Koin Annotations	KSP Version	Kotlin Version
1.4.x	1.9.x	1.9.x
1.3.x	1.9.x	1.9.x
1.2.x	1.8.x	1.8.x

Basic Usage

@Single
class MyComponent

@Module
class MyModule

// Import generated extensions
import org.koin.ksp.generated.*

fun main() {
    startKoin {
        modules(MyModule().module)
    }
}

KSP Options

// build.gradle.kts
ksp {
    arg("KOIN_CONFIG_CHECK", "true")  // Enable compile-time validation
}

KMP Setup (Complex)

// shared/build.gradle.kts
plugins {
    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")
        }
    }
}

dependencies {
    // Per-platform KSP configuration required
    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")
}

Migration to Compiler Plugin

Step 1: Update Kotlin

Ensure you're using Kotlin 2.x:

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.0.0"
}

Step 2: Remove KSP

Remove KSP plugin and dependencies:

// Remove these:
plugins {
    // id("com.google.devtools.ksp")  // Remove
}

dependencies {
    // ksp("io.insert-koin:koin-ksp-compiler:...")  // Remove
}

Step 3: Add Compiler Plugin

// settings.gradle.kts
plugins {
    id("io.insert-koin.compiler.plugin") version "1.0.0" apply false
}

// build.gradle.kts
plugins {
    id("io.insert-koin.compiler.plugin")
}

Step 4: Keep Your Code

Your annotations stay exactly the same:

// This code doesn't change!
@Singleton
class MyService(val repository: MyRepository)

@Factory
class MyRepository

@KoinViewModel
class MyViewModel(val service: MyService)

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

Step 5: Clean Up

Delete generated files:

rm -rf build/generated/ksp

Rebuild your project.

What Stays the Same

Annotation	Status
@Singleton / @Single	✅ Same
@Factory	✅ Same
@Scoped	✅ Same
@KoinViewModel	✅ Same
@KoinWorker	✅ Same
@Named	✅ Same
@InjectedParam	✅ Same
@Property	✅ Same
@Module	✅ Same
@ComponentScan	✅ Same
@Configuration	✅ Same

What Changes

Aspect	KSP	Compiler Plugin
Build plugin	com.google.devtools.ksp	io.insert-koin.compiler.plugin
Dependencies	ksp() configuration	None required
Generated files	Visible in build/	Hidden
KMP setup	Per-platform KSP	Single plugin

Timeline

KSP annotations will be removed in a future Koin version. We recommend migrating as soon as possible.

Help

If you encounter issues during migration:

• Check Troubleshooting
• Ask on Slack
• Open an issue on GitHub

Next Steps

• Compiler Plugin Setup - Complete setup guide
• Migration Guide - Detailed migration steps