Mark Compose models stable without adding Compose to core modules
Compose treats a model as unstable when it comes from another package, even if every property inside it is stable. A small annotation-only library lets pure Kotlin, JVM, or core modules declare stability for the compiler without pulling in the full Compose runtime.
Why external models lose stability
Stability tells Compose whether an object can be treated as equivalent across recompositions. When state or parameters are stable, Compose can skip work that would otherwise run again. That decision directly shapes UI responsiveness, so unstable parameters deserve attention even in small model classes.
A class becomes unstable if any of its property types are unstable. Interface types such as List are a common trigger. Adding a stability annotation tells the compiler that the class should be treated as stable despite the types it contains, provided the class genuinely upholds that guarantee.
A different problem appears at package boundaries. A class made only of stable types is stable by default in its own module, yet the compiler still treats it as unstable when it arrives from another package, an SDK, or a separate module. The consuming app cannot fix that from the call site, and the producing module may have no reason to depend on Compose.
The annotation-only fix for core modules
Adding the full Compose runtime to a plain model module solves the annotation problem but creates a larger one. Runtime APIs for effects, snapshots, and state collection would become available in code where they do not belong, increasing the chance of misuse through IDE autocomplete.
The annotation-only approach separates the compiler signal from runtime behaviour. Core modules import only the stability annotations, mark their models, and keep Compose runtime features out of scope. Because the annotations are consumed at compile time, the dependency is declared as compileOnly.
Use this pattern when a core or pure JVM module exposes models to Compose consumers. It is a poor fit when the module already uses Compose runtime APIs, since then the full runtime dependency is already appropriate.
Choosing between the official and earlier libraries
An earlier third-party library offered the same idea before an official option existed. It remains useful for projects that cannot yet meet the official library's build requirement.
The official library needs compileSdkVersion 34 or higher to build and verify correctly, although it supports devices down to API 21. Most current projects already target that level, but libraries and SDKs pinned below it may need the older alternative until their build tools are updated.
Configuration files, strong skipping, and a practical checklist
Two additional mechanisms can reduce stability friction in multi-module apps. A stability configuration file, supported from Compose Compiler 1.5.5, can declare classes you do not own as stable, including standard library types. Strong skipping mode makes restartable composables skippable even when parameters are unstable, while non-restartable composables stay unskippable; it is on by default in Kotlin 2.0.20.
These options help app teams, but they do not remove the case for explicit annotations in libraries and SDKs. A library cannot assume every consumer will configure stability correctly, so marking its own models gives consumers a reliable performance baseline.
Decision checklist: confirm the model truly is stable, check whether it crosses a package or module boundary, prefer the official annotation library when compile SDK 34 or higher is available, consider the earlier library below that threshold, and add a configuration file or strong skipping where they fit the app architecture.
| Approach | Best for | Key requirement or limit |
|---|---|---|
| Official runtime annotation library | Core, pure JVM, or multiplatform modules exposing models to Compose | compileOnly dependency; compileSdkVersion 34 or higher, min SDK down to API 21 |
| Compose Stable Marker | Libraries or SDKs still below compile SDK 34 | Earlier third-party alternative with similar behaviour |
| Stability configuration file | Classes you do not control, such as standard library types | Compose Compiler 1.5.5 or later |
| Strong skipping mode | Restartable composables with unstable parameters | Enabled by default in Kotlin 2.0.20; non-restartable composables remain unskippable |
Comparison based on the captured article; verify current versions before publication.
Frequently asked questions
Does the runtime annotation library need to ship in the app at runtime?
No. The annotations are used by the Compose compiler at build time to classify a class as stable. That is why the dependency can be declared with compileOnly rather than implementation.
What compile SDK does the official library require?
The official library needs compileSdkVersion 34 or higher for building and verification, even though its minimum SDK goes down to API 21. If a library or SDK is still below compile SDK 34, the earlier Compose Stable Marker library remains an alternative.
What other options can improve stability in a multi-module app?
A stability configuration file, available from Compose Compiler 1.5.5, can mark classes you do not control, such as standard library types, as stable. Strong skipping mode, enabled by default in Kotlin 2.0.20, makes restartable composables skippable even with unstable parameters, while non-restartable composables remain unskippable.