Stabilizing Compose Types

Stabilizing Compose Types — Three Tiers, In Order

Once a diagnosis (see ../diagnosing-compose-stability/SKILL.md) has named the unstable types, this skill walks Claude through fixing them. The strategy is a strict three-tier waterfall: (1) make the type truly stable by structural rewrite (val + immutable fields) — no annotation needed; (2) annotate with @Immutable or @Stable when the source is owned and the contract is honored; (3) use stabilityConfigurationFile for third-party or Java types. DO NOT invert this order — annotations are a contract, not a magic spell.

When to use this skill

• The compiler report (composables.txt / classes.txt) shows one or more unstable parameters.
• The developer asks how to stabilize a domain class, a List<Foo> parameter, java.time.LocalDateTime, or a third-party type.
• The developer mentions @Immutable, @Stable, compose-stable-marker, compose-runtime-annotation, kotlinx.collections.immutable, stabilityConfigurationFiles, or stability_config.conf.
• A @TraceRecomposition log shows recomposition happening because an argument is allocated fresh every recomposition.

When NOT to use this skill

• The unstable types are not yet identified — run ../diagnosing-compose-stability/SKILL.md first.
• The symptom is a wrong-phase state read (Modifier.alpha(state.value)); use ../../recomposition/deferring-state-reads/SKILL.md.
• The symptom is a derivedStateOf problem; use ../../recomposition/choosing-derivedstateof/SKILL.md.
• A Flow<T> parameter is the cause; the fix is to collect upstream — see ../../side-effects/collecting-flows-safely/SKILL.md rather than annotating Flow as stable.

Prerequisites

• ../diagnosing-compose-stability/SKILL.md has been run; the developer has a concrete list of unstable types.
• Kotlin 2.0.0+ with org.jetbrains.kotlin.plugin.compose applied. Strong Skipping is on by default.
• For pure-Kotlin / data modules without compose-runtime: either androidx.compose.runtime:runtime-annotation (official) or com.github.skydoves:compose-stable-marker (legacy) on the classpath. Both expose @Stable / @Immutable / @StableMarker without dragging in the full runtime.
• For tier-3 fixes: Compose Compiler 1.5.5+ for stabilityConfigurationFiles DSL support (plural; the older singular stabilityConfigurationFile property is deprecated, see footnote below).

Workflow — decision tree

• 1. Do we own the source of the unstable type? If yes, use tier 1 or tier 2. If no (Java stdlib, third-party SDK), jump to tier 3.

• 2. Tier 1 — restructure to truly stable. Can every property be a val of an already-stable type? If yes, MUST make that change first. No annotation is needed and no contract is implied. The compiler will infer stability automatically.

// WRONG
data class Snack(
    var name: String,
    val tags: Set<String>,
)
// WRONG because: `var name` is an observable that does not notify Compose, and `Set<String>` is the standard library interface so its stability is Unknown — the data class is unstable on two axes.

// RIGHT
@Immutable
data class Snack(
    val name: String,
    val tags: ImmutableSet<String>,
)

• 3. Is the unstable property a collection? Replace kotlin.collections.List, Set, Map with kotlinx.collections.immutable.ImmutableList, ImmutableSet, ImmutableMap. Build with persistentListOf(), persistentSetOf(), persistentMapOf() factories or .toImmutableList() adapters. The kotlinx-collections-immutable artifact ships a known-stable bitmask 0b1 recognized by the Compose Compiler. PREFERRED: prefer this over whitelisting kotlin.collections.* in stability_config.conf because the type system enforces immutability.

• 4. Is the source a pure-Kotlin / data module that does not depend on compose-runtime? Use androidx.compose.runtime:runtime-annotation (official, recommended) or com.github.skydoves:compose-stable-marker (legacy). Both let the data module annotate types without pulling in the full Compose runtime. Skydoves hot take #6: pure-Kotlin / data modules can use compose-stable-marker (or newer official compose-runtime-annotation) without pulling in full compose-runtime.

// shared data module — build.gradle.kts
dependencies {
    // Official, preferred:
    compileOnly("androidx.compose.runtime:runtime-annotation:<version>")
    // Or legacy skydoves:
    // implementation("com.github.skydoves:compose-stable-marker:<version>")
}

• 5. Tier 2 — choose @Immutable or @Stable. If every property is val AND every nested value is itself immutable AND equals() is structural, use @Immutable. Otherwise — for types whose values can change but whose mutations are observed by Compose (e.g. holders containing MutableState) — use @Stable.

The compiler treats @Immutable more aggressively than @Stable. For @Immutable types, when every constructor argument at a call site is a compile-time constant (e.g. literal numbers, top-level vals of stable types, or other @Immutable-with-constant-args), the compiler performs static expression promotion: the constructed instance is hoisted into a singleton, the lambda capture sites are de-duplicated, and the @Immutable parameter is marked @static in composables.txt. Most articles describe @Stable and @Immutable as interchangeable — they are not.

// RIGHT — @Immutable: every property val, every property type immutable
@Immutable
data class ThemeColors(
    val primary: Color,
    val onPrimary: Color,
    val background: Color,
)

// RIGHT — @Stable: mutable but mutations notify Compose via Snapshot
@Stable
class CartState {
    var total: Money by mutableStateOf(Money.ZERO)
    val lines: SnapshotStateList<Line> = mutableStateListOf()
}

• 6. Tier 3 — third-party or Java types. Use stabilityConfigurationFiles (plural). Create stability_config.conf at the project root listing exact-class or wildcard patterns; wire it into the composeCompiler { } block via stabilityConfigurationFiles.add(...). Full grammar lives in references/stability-config-syntax.md.

// build.gradle.kts (root or composable module)
composeCompiler {
    stabilityConfigurationFiles.add(
        rootProject.layout.projectDirectory.file("stability_config.conf")
    )
}

Footnote — legacy form. Older projects may still wire the file via the singular property stabilityConfigurationFile = .... That property is @Deprecated("Use the stabilityConfigurationFiles option instead") in modern Compose Compiler Gradle plugin releases — prefer the plural stabilityConfigurationFiles.add(...) shown above.

# stability_config.conf — opt-in contract
java.time.LocalDateTime
java.time.LocalDate
kotlin.collections.List
kotlin.collections.Set
kotlin.collections.Map
com.example.thirdparty.**

• 7. Nothing in tiers 1-3 fits? Wrap in a @Stable class StableHolder<T>(val item: T). This is the escape hatch — the holder's identity is stable, equality delegates to item, and Compose can skip on it.

@Stable
class StableHolder<T>(val item: T) {
    override fun equals(other: Any?) = other is StableHolder<*> && other.item == item
    override fun hashCode() = item?.hashCode() ?: 0
}

• 8. Flow<T> parameters — DO NOT annotate as stable. Skydoves hot take #4: Flow parameters are unstable. Don't pass flows to composables; collect them in a ViewModel or with collectAsStateWithLifecycle.

// WRONG
@Composable
fun Feed(items: Flow<List<Item>>) { /* ... */ }
// WRONG because: Flow has no observable identity; the composable cannot skip on it, and a downstream `collectAsState` here detaches from lifecycle.

// RIGHT — collect upstream and pass the resolved value
@Composable
fun FeedRoute(viewModel: FeedViewModel = viewModel()) {
    val items by viewModel.items.collectAsStateWithLifecycle()
    Feed(items = items)
}

@Composable
fun Feed(items: ImmutableList<Item>) { /* ... */ }

• 9. Re-run the diagnostic skill to verify the previously unstable params are now stable or runtime.