Koin for SDK & Libraries - Relocate your own version of Koin

Koin Embedded allows SDK and library developers to package a relocated version of Koin with a different package name, preventing dependency conflicts when your library is used in applications that also use Koin.

info

This feature is currently in Beta. We welcome feedback and contributions. Contact the Koin Team with questions or suggestions.

Why Use Koin Embedded?

The Problem

When you develop an Android SDK or Kotlin library that uses Koin internally, you may encounter dependency conflicts if the consuming application also uses Koin:

// Your SDK uses Koin 3.5.0
implementation("io.insert-koin:koin-core:3.5.0")

// Consumer app uses Koin 4.0.0
implementation("io.insert-koin:koin-core:4.0.0")
// ❌ Conflict! Only one version will be used at runtime

Issues this causes:

• Version conflicts between your SDK's Koin version and the app's Koin version
• Runtime errors due to API changes between versions
• Breaking changes affecting either your SDK or the consuming app
• Forced upgrades on library consumers

The Solution: Package Relocation

Koin Embedded relocates Koin's package from org.koin.* to a custom namespace like embedded.koin.* or com.yourcompany.internal.koin.*:

// Before relocation
import org.koin.core.module.dsl.singleOf
import org.koin.core.context.startKoin

// After relocation
import embedded.koin.core.module.dsl.singleOf
import embedded.koin.core.context.startKoin

This allows your SDK and the consuming app to use different Koin versions independently:

// ✅ Your SDK uses embedded Koin 3.5.0
implementation("io.insert-koin:embedded-koin-core:3.5.0")

// ✅ Consumer app uses standard Koin 4.0.0
implementation("io.insert-koin:koin-core:4.0.0")
// No conflict! Two separate packages

Use Cases

Koin Embedded is ideal for:

• Android SDKs - Payment SDKs, Analytics SDKs, Authentication libraries
• Kotlin Libraries - Shared business logic libraries used across multiple apps
• Enterprise Libraries - Internal company libraries with DI needs
• Third-party Integrations - Libraries that integrate external services

danger

Not recommended for regular app development. Use standard Koin for your applications. Embedded Koin is specifically for library authors who need to avoid dependency conflicts.

Pre-Built Embedded Version (Beta)

Kotzilla provides pre-built embedded versions of Koin with the embedded.koin.* package namespace.

Available Packages

Package	Description
embedded-koin-core	Core Koin functionality
embedded-koin-android	Android-specific extensions

Package relocation: org.koin.* → embedded.koin.*

Setup

Add the Kotzilla repository to your Gradle configuration:

Kotlin DSL (build.gradle.kts):

repositories {
    maven {
        url = uri("https://repository.kotzilla.io/repository/kotzilla-platform/")
    }
}

dependencies {
    implementation("io.insert-koin:embedded-koin-core:$koin_version")
    implementation("io.insert-koin:embedded-koin-android:$koin_version")
}

Groovy DSL (build.gradle):

repositories {
    maven {
        url 'https://repository.kotzilla.io/repository/kotzilla-platform/'
    }
}

dependencies {
    implementation "io.insert-koin:embedded-koin-core:$koin_version"
    implementation "io.insert-koin:embedded-koin-android:$koin_version"
}

Using Embedded Koin

Your code uses the relocated package names:

// Import from embedded package
import embedded.koin.android.ext.koin.androidContext
import embedded.koin.core.context.startKoin
import embedded.koin.core.module.dsl.singleOf
import embedded.koin.dsl.module

class YourSDK {
    fun initialize(context: Context) {
        startKoin {
            androidContext(context)
            modules(sdkModule)
        }
    }
}

private val sdkModule = module {
    singleOf(::AnalyticsService)
    singleOf(::ApiClient)
}

Everything works the same, just with embedded.koin.* instead of org.koin.*!

Custom Relocation (Beta)

For complete control over the package name, use the Koin relocation scripts to build your own embedded version.

Benefits of Custom Relocation

• Custom package name - Use your company's package namespace
• Version control - Pin to a specific Koin version
• Custom builds - Include only the modules you need
• Security - Avoid public package names

Using Relocation Scripts

The koin-embedded project provides scripts to rebuild Koin with custom package names.

Example custom relocation:

org.koin.* → com.acme.sdk.internal.koin.*

Steps:

1. Clone the relocation scripts repository:

   git clone https://github.com/InsertKoinIO/koin-embedded.git
   cd koin-embedded

2. Configure your custom package name in the relocation script

3. Run the relocation process:

   ./scripts/relocate.sh com.acme.sdk.internal.koin

4. Publish to your internal Maven repository or include as a local dependency

For detailed instructions, see the Koin Embedded repository.

Best Practices

SDK Development

1. Use embedded Koin internally - Keep it as an implementation detail
2. Don't expose Koin types in your public API - Avoid leaking KoinComponent, Module, etc. in your SDK's public interface
3. Initialize in isolation - Use a separate Koin instance for your SDK
4. Document the dependency - Mention in your SDK docs that you use Koin internally

Example: Isolated SDK Initialization

// ✅ Good - Koin is an internal implementation detail
class PaymentSDK private constructor(context: Context) {

    companion object {
        private var instance: PaymentSDK? = null

        fun initialize(context: Context): PaymentSDK {
            return instance ?: PaymentSDK(context).also { instance = it }
        }
    }

    private val koinApp = koinApplication {
        androidContext(context)
        modules(paymentModule)
    }

    private val paymentService: PaymentService = koinApp.koin.get()

    fun processPayment(amount: Double): PaymentResult {
        return paymentService.process(amount)
    }
}

// ❌ Bad - Exposing Koin in public API
class PaymentSDK : KoinComponent {  // Don't extend KoinComponent publicly
    fun getPaymentService(): PaymentService = get()  // Don't expose get()
}

Version Management

1. Pin to a specific version - Don't use version ranges for embedded Koin
2. Test compatibility - Verify your SDK works with different Koin versions in consuming apps
3. Update cautiously - Test thoroughly before updating embedded Koin version

Documentation

Mention in your SDK documentation:

## Dependencies

This SDK uses Koin internally (embedded version) for dependency injection.
The embedded version is isolated and will not conflict with Koin usage
in your application.

**Internal dependency:** `embedded-koin-core:3.5.0`
**Package namespace:** `embedded.koin.*`

Migration Guide

From Standard Koin to Embedded Koin

1. Update dependencies:

// Before
implementation("io.insert-koin:koin-core:3.5.0")
implementation("io.insert-koin:koin-android:3.5.0")

// After
implementation("io.insert-koin:embedded-koin-core:3.5.0")
implementation("io.insert-koin:embedded-koin-android:3.5.0")

2. Update imports:

Use your IDE's "Replace in Files" to update package names:

• Find: import org.koin
• Replace: import embedded.koin

3. Test thoroughly:

• Verify all functionality works with relocated packages
• Test in an app that also uses standard Koin
• Confirm no dependency conflicts

From Embedded Koin to Standard Koin

If you decide embedded Koin isn't needed:

1. Replace embedded-koin-* dependencies with standard koin-*
2. Update imports from embedded.koin back to org.koin
3. Test compatibility with consuming apps

Troubleshooting

Build Issues

Problem: Repository not found

Could not find embedded-koin-core:3.5.0

Solution: Ensure Kotzilla repository is configured:

repositories {
    maven("https://repository.kotzilla.io/repository/kotzilla-platform/")
}

Runtime Issues

Problem: ClassNotFoundException at runtime

Solution: Verify you're using the embedded package names everywhere:

// Wrong
import org.koin.core.context.startKoin

// Correct
import embedded.koin.core.context.startKoin

Dependency Conflicts

Problem: Still seeing version conflicts

Solution: Ensure you're not mixing standard and embedded Koin:

// ❌ Don't mix
implementation("io.insert-koin:koin-core:3.5.0")           // Standard
implementation("io.insert-koin:embedded-koin-core:3.5.0")  // Embedded

// ✅ Use only embedded
implementation("io.insert-koin:embedded-koin-core:3.5.0")

Limitations

• Beta status - API may change, use with caution in production
• Limited modules - Not all Koin modules may be available in embedded form
• Build complexity - Custom relocation requires additional build steps
• Maintenance overhead - Need to keep embedded version updated manually

Feedback & Support

This is a Beta feature. We value your feedback:

• Report issues: GitHub Issues
• Questions: Koin Slack
• Email: koin@kotzilla.io

See Also

• Koin Embedded Repository - Relocation scripts and documentation
• Kotzilla Repository - Pre-built embedded versions
• Koin Core Documentation - Standard Koin usage