kotlin-inject-anvil

Scopes in kotlin-inject-anvil are marker classes used to connect contributions to merged components. They do not have inherent logic.

Important: These scope markers are independent of kotlin-inject's internal scoping mechanism. You must still use kotlin-inject scoping (like @SingleIn) to manage object lifecycles.

It is highly recommended to use the @SingleIn annotation provided by the runtime-optional module for consistency.

object AppScope // Marker class

@Inject
@SingleIn(AppScope::class) // kotlin-inject scope
@ContributesBinding(AppScope::class) // anvil connection
class RealAuthenticator : Authenticator

You can manually trigger a release (either a production or snapshot release, depending on the version defined in gradle.properties) using the following command:

./gradlew clean publish --no-build-cache

When using @ContributesBinding with kotlin-inject's @Assisted annotation, the factory is injected as a lambda where the base type is the return type.

Note: If you require a strongly typed interface instead of a lambda, you should create an explicit Factory interface and bind that manually.

interface Authenticator {
    fun authenticate(): Result
}

@Inject
@ContributesBinding(AppScope::class)
class RealAuthenticator(
    @Assisted val credentials: Credentials,
): Authenticator {
    override fun authenticate(): Result = sendAuthenticationRequest(credentials)
}

@Inject
class LoginScreen(val authenticatorFactory: (Credentials) -> Authenticator) {
    fun login(credentials: Credentials) {
        val authenticator = authenticatorFactory(credentials)
        authenticator.authenticate()
    }
}

To use kotlin-inject-anvil, you need to add the KSP compiler and the runtime module to your dependencies. It is strongly recommended to also include the runtime-optional module to access the @SingleIn scope annotation and @ForScope qualifier.

Ensure you have already set up kotlin-inject and KSP for your Kotlin Multiplatform project as per their official documentation.

dependencies {
    kspCommonMainMetadata "software.amazon.lastmile.kotlin.inject.anvil:compiler:$version"
    commonMainImplementation "software.amazon.lastmile.kotlin.inject.anvil:runtime:$version"

    // Optional module, but strongly suggested to import. It contains the
    // @SingleIn scope and @ForScope qualifier annotation together with the
    // AppScope::class marker.
    commonMainImplementation "software.amazon.lastmile.kotlin.inject.anvil:runtime-optional:$version"
}

In Kotlin Multiplatform, generated code might not be accessible from common or platform-specific source sets (like iosMain). To solve this, use the @CreateComponent annotation on an expect fun in your common code. The KSP plugin will generate the actual fun implementation.

@MergeComponent(AppScope::class)
@SingleIn(AppScope::class)
abstract class AppComponent(
    @get:Provides userId: String,
)

// The actual implementation will be generated by KSP
@CreateComponent
expect fun create(appId: String): AppComponent

// Or using a receiver type
@CreateComponent
expect fun KClass<AppComponent>.create(appId: String): AppComponent

To install the current development version of the project into your local Maven repository for testing or local development, run the following Gradle command:

./gradlew publishToMavenLocal

If a built-in kotlin-inject-anvil symbol processor does not meet your requirements, you can disable it using KSP options. To disable a processor, set the KSP argument key to the fully qualified name of the symbol processor and set its value to "disabled". Any other value will leave the processor enabled.

All built-in symbol processors are located in the software.amazon.lastmile.kotlin.inject.anvil.processor package.

ksp {
    arg("software.amazon.lastmile.kotlin.inject.anvil.processor.ContributesBindingProcessor", "disabled")
}

To pick up all contributions for a specific scope, replace the standard @Component annotation with @MergeComponent(Scope::class). This generates a new component class that merges all contributions to that scope.

Instantiation

Use the generated .create() function to instantiate the component at runtime. If your component has parameters, pass them to .create().

// Standard component with parameters
@MergeComponent(AppScope::class)
@SingleIn(AppScope::class)
abstract class AppComponent(
    @get:Provides val userId: String,
)

// Instantiate with parameter
val component = AppComponent::class.create("userId")

Use the @ContributesTo annotation to add a component interface to a specific scope. This makes the provider methods within that interface available to the final merged component of that scope.

@ContributesTo(AppScope::class)
interface AppIdComponent {
    @Provides
    fun provideAppId(): String = "demo app"
}

The @ContributesSubcomponent annotation allows you to define a subcomponent in any Gradle module. The final subcomponent is generated when the parent component is merged.

@ContributesSubcomponent(LoggedInScope::class)
@SingleIn(LoggedInScope::class)
interface RendererComponent {

    @ContributesSubcomponent.Factory(AppScope::class)
    interface Factory {
        fun createRendererComponent(): RendererComponent
    }
}