compose-stability-diagnostics

Compose stability diagnostics

Core principle

Compose parameter fixes start from evidence. First identify the compiler mode and the parameter comparison behavior, then change the model or call site that is actually defeating skipping.

With Kotlin 2.0.20+ strong skipping is enabled by default. Unstable parameters no longer automatically make restartable composables non-skippable, but unstable parameters compare by instance identity (===) while stable parameters compare by equality (equals). Churny unstable instances can still defeat skipping.

Diagnostic procedure

1. Confirm the symptom: recomposition counts, compiler report output, or a suspected churny parameter.
2. Identify compiler mode: Kotlin/Compose compiler version and whether strong skipping is enabled.
3. Generate or read the Compose compiler reports for the shipped variant.
4. For each suspicious parameter, decide whether the problem is stability semantics, instance churn, or a caller-created lambda/derived value.
5. Apply the lightest fix that makes the type/call site truthful.
6. Re-measure the same interaction or re-read the same report before claiming the issue is fixed.

1. Interpret strong skipping first

On Kotlin 2.0.20+, strong skipping is enabled by default. In that mode:

• Restartable composables are skippable even when parameters are unstable, unless explicitly opted out.
• Stable parameters compare with equals.
• Unstable parameters compare with instance equality (===).
• Lambdas inside composables are automatically remembered based on captures.

Ask: "will these parameters compare the way I expect, and are callers creating new unstable instances every frame?"

For older compiler setups or strong skipping disabled, the legacy rule still matters: a restartable composable with unstable parameters may be restartable but not skippable.

2. Generate compiler reports

With Kotlin 2.0+ the Compose Compiler is configured through the Kotlin Gradle plugin:

plugins {
    alias(libs.plugins.android.application) // or android.library / jvm
    alias(libs.plugins.kotlin.android)      // or kotlin.multiplatform / kotlin.jvm
    alias(libs.plugins.compose.compiler)
}

if (providers.gradleProperty("composeReports").orNull == "true") {
    composeCompiler {
        reportsDestination = layout.buildDirectory.dir("compose_compiler")
        metricsDestination = layout.buildDirectory.dir("compose_compiler")
    }
}