compose-stability-diagnostics

Compose stability diagnostics

Core principle

Compose performance problems from parameters are about whether inputs compare cheaply and predictably across recompositions. With Kotlin 2.0.20+ strong skipping is enabled by default, so unstable parameters no longer automatically make restartable composables non-skippable. That does not make stability irrelevant: unstable parameters are compared by instance identity (===), stable parameters by equality (equals), and churny instances can still defeat skipping.

First identify the compiler mode you are on, then read reports in that context.

When to use this skill

• A composable or screen recomposes more than expected and parameter churn is suspected.
• A UI-state/model class is passed to composables and contains List, Set, Map, ranges, Java time/money types, or third-party types.
• composables.txt / classes.txt shows unstable parameters or non-skippable composables.
• A project uses Kotlin < 2.0.20, disables strong skipping, or has old Compose compiler report guidance.

1. Start with strong skipping

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.

That means the question changes from "is this composable skippable at all?" to "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")
    }
}