skip to content

As the lead of a multi-module Jetpack Compose codebase, what stability policy would you set: a stability configuration file, annotated models, or relying on strong skipping alone?

level: principalimportance: should knowfreq 30%

answer

  1. start from the default mode
  2. promises the compiler never checks
  3. types you do not own
  4. cost of equals on big lists
  5. measure before you annotate

basics

~20 s

Rely on strong skipping plus a rule against re-allocating equal UI models in composition. Keep one shared stability configuration file for types you do not own, and allow @Immutable or @Stable only on small models with cheap equals() where measurement shows churn.

solid answer

~40 s

I would start from strong skipping, the default since Kotlin 2.0.20, and make the team rule about allocation: UI models are produced where screen state is built, not mapped in composable bodies, so instance comparison works. Annotations and the configuration file are both **unchecked promises**, like `!!`: a wrong one makes a composable skip and show stale data. So I would allow `@Immutable` or `@Stable` on small, genuinely immutable models whose `equals()` is cheap, where a source keeps emitting equal new instances, using `runtime-annotation` in data modules since Compose 1.9. A single root `stabilityConfigurationFile` passed to every module covers types we do not own, such as `java.time.LocalDateTime`, and is reviewed like code. I would not blanket-annotate list-holding models or add `kotlin.collections.*` by default, because element-by-element `equals()` can cost more than the recomposition it saves.

go deeper

for a junior

Know that Compose decides whether to re-run a composable by comparing its parameters, and that annotations like @Immutable change how it compares them.

for a middle

Explain the three levers (strong skipping, annotations, a configuration file) and why the last two are promises the compiler does not verify.

for a senior

Show where each lever bit you: an annotation that hid a mutation, a list made stable that slowed a screen, a data source that re-allocated equal objects.

for a principal

Own the trade: an allocation rule and reviewed exceptions over blanket annotation, one shared configuration file, and evidence from reports before any new promise.

## The decision In a multi-module Jetpack Compose codebase, stability decides how Compose compares a composable's parameters during recomposition. A lead has to set one policy so twenty engineers do not each invent their own. There are three levers, and they combine: 1. **Rely on strong skipping**, the Compose compiler's default since Kotlin 2.0.20: unstable parameters are compared by instance (`===`), stable ones with `equals()`. 2. **Annotate models** with `@Immutable` or `@Stable`, so the compiler treats them as stable. 3. **Keep a stability configuration file**, a plain-text list of classes or packages the compiler should treat as stable, passed with `stabilityConfigurationFile` (available since Compose Compiler 1.5.5). There is no single right answer; the right mix depends on the data layer, the module graph and how much the team trusts its own promises. ## What each lever costs | Lever | Strengths | Risks | |---|---|---| | Strong skipping alone | nothing to maintain; `===` is constant-time | equal but new instances still recompose | | Annotations | precise, live next to the class | unchecked; wrong ones cause stale UI; data modules need `runtime-annotation` | | Configuration file | central; covers types you cannot annotate | unchecked; wildcards cover classes nobody reviewed | Both annotations and the file are **promises, not checks**. The documentation compares an annotation to Kotlin's `!!`: you override what the compiler would infer. If a class marked stable is mutated in place, Compose skips the composables that receive it and the screen shows old data. That bug is harder to find than an extra recomposition. ## A policy that holds up A defensible default for most teams: - **Strong skipping on everywhere**, which needs no work on a current Kotlin. - **An allocation rule.** UI models are built where screen state is produced, not mapped inside composable bodies. Most "it recomposes every frame" reports on a current toolchain are fresh instances, and this rule fixes them without any promise. - **Annotations by exception.** `@Immutable` or `@Stable` only on small models that really are immutable, or whose changes go through Compose `State`, and only when a source keeps emitting equal new instances (a database reader re-reading a list is the usual case). Since Compose 1.9, data modules can use `androidx.compose.runtime:runtime-annotation` instead of a dependency on the Compose runtime. - **One configuration file at the project root**, passed to every module, for types the team does not own, such as `java.time.LocalDateTime`. The compiler runs per module, so a per-module file is possible, but a single shared file is easier to review. - **Reviews treat both as code.** A new entry needs a reason, and the configuration file gets an owner. ## Collections are where policies go wrong The compiler infers `List`, `Set` and `Map` unstable because an implementation could be mutable. Teams then reach for one of three fixes: - adding `kotlin.collections.*` to the configuration file; - converting to kotlinx immutable collections, which the compiler recognises but which are still alpha; - annotating the class that holds the list. The documentation now warns against doing this by default. Under strong skipping an unstable list is already compared by reference, in constant time. Making it stable switches to `equals()`, which compares every element on every pass and can cost more than the recomposition it was meant to save. Reserve it for cases where structural equality is actually needed. ## What not to standardise - **Skippability as a goal.** The documentation says not every composable should be skippable: one that rarely recomposes, one that only calls skippable children, or one whose parameters have expensive `equals()` gains nothing. - **Pre-2.0.20 folklore.** Policies written when an unstable parameter meant "never skips" over-annotate. - **Annotating data-layer classes to fix a UI problem** when a UI-module wrapper keeps the data layer free of any Compose dependency. ## How to know the policy works Keep the evidence cheap. Compose compiler reports (`reportsDestination`) show the stability the compiler inferred for each module, and recomposition counts in Android Studio's Layout Inspector show whether a screen skips. Device-level measurement belongs to the benchmarking discipline. Revisit the policy when the Kotlin version, the data layer or the module graph changes, because each of those moves what the compiler can infer.

  • A team wants to add kotlin.collections.* to the shared stability configuration file. What do you say?
    It is allowed by the documentation, but it is a promise that no `List` in the codebase is ever mutated behind Compose's back, and it switches those comparisons from constant-time `===` to element-by-element `equals()`. Under strong skipping I would only accept it with a measured problem that structural equality solves.
  • Would you put the Compose compiler on the data modules so their classes are inferred stable?
    It works, but it couples the data layer to Compose's toolchain. I prefer UI-module wrappers or a configuration-file entry, and since Compose 1.9 a data module that genuinely needs annotations can depend on `runtime-annotation` alone.

  • Every model should be @Immutable so every composable can skip.
  • The compiler checks that a class marked @Stable is really stable.
  • With strong skipping on, stability annotations are never needed.
  • Making every collection stable is always cheaper than recomposing.

Assumes Compose 1.12 with Kotlin 2.0.20 or newer (strong skipping by default), runtime-annotation since Compose 1.9, and stabilityConfigurationFile since Compose Compiler 1.5.5.