Real-time composable stability analysis with editor gutter icons, hover tooltips, inline parameter hints and code inspections; runtime @TraceRecomposition logging plus Gradle tasks for recomposition tracing and reports.
Compose Stability Analyzer provides real-time analysis of your Jetpack Compose composable functions' stability directly within Android Studio or IntelliJ. It helps you understand why a composable function is stable or unstable, and offers detailed insights through recomposition tracing and logging.
Additionally, you can trace the reason of your composable function is triggered recomposition with a TraceRecomposition annotation, and export stability compatibility reports using Gradle tasks for reviewing the new stability changes.
You can change the colors used for stability indicators to match your IDE theme, enabling Strong Skipping mode for analyzing, visual indicators (showing gutter icons, warnings, inline hints), change parameter hint colors, enabling analysis in test source sets, set a stability configuration file, add ignored type patterns to exclude from the stability analysis.
The sponsors listed below made it possible for this project to be released as open source. Many thanks to all of them for their support!
Vision Agents (GitHub) is an open-source Video AI framework for building real-time voice and video applications. The framework is edge/transport agnostic, meaning developers can also bring any edge layer they like.
CodeRabbit is an AI-powered code review platform that integrates directly into pull-request workflows and IDEs, examining code changes in context and suggesting improvements.
Firebender is the most powerful AI coding agent in Android Studio. It can create entire compose UIs from Figma links, generate UML diagrams, and even understand your voice input.
Jetpack Compose Mechanisms takes you from "how to use Compose" into "how Compose actually works," tracing the AOSP source line by line through the compiler, runtime, and UI layers beneath every Composable, with practical, production-ready examples from the author's own Compose tooling and libraries. It then ties all three layers together into deep, real-world performance tuning, from stability inference to the skip decision. Fully updated for Kotlin 2.4.0 and Compose Compiler 2.4.0.
The Compose Stability Analyzer IntelliJ Plugin brings visual stability analysis directly into your IDE (Android Studio), helping you identify and fix performance issues while you code. Instead of waiting for runtime or build-time reports, you get instant feedback right in Android Studio or IntelliJ IDEA.
This plugin provides real-time visual feedback about your composables' stability through nine main features:
Note: You don’t need to make every composable function skippable or all parameters stable, these are not direct indicators of performance optimization. The goal of this plugin isn’t to encourage over-focusing on stability, but rather to help you explore how Compose’s stability mechanisms work and use them as tools for examining and debugging composables that may have performance issues. For more information, check out Compose Stability Analyzer: Real-Time Stability Insights for Jetpack Compose.
You can download the Compose Stability Analyzer Plugin with the steps below:
Open Android Studio > Settings (or Preferences) > Plugins > Marketplace > Compose Stability Analyzer > Install
If you see gutter icons and tooltips, you're all set! 🎉 You can also install this plugin directly on your IDE on JetBrains Marketplace.
Gutter icons appear in the left margin of your editor, giving you instant visual feedback on your composable functions:
This is the fastest way to spot performance problems. Just glance at the left margin, if you see red dots, those composables need attention.
Also, when you hover your mouse over a composable function name, a detailed tooltip appears showing:
This gives you the why behind the gutter icon color. You don't just see that a composable is unstable, you see exactly which parameters are the problem.
Inline hints are small badges that appear right next to parameter types, showing the stability of each individual parameter. This is the most detailed level of feedback, you see stability information for every single parameter at a glance.
Code inspections go beyond visual indicators, they actively suggest improvements. When you have an unstable composable, the plugin can:
This is like having an automated code review for Compose performance. The plugin doesn't just tell you about problems, it helps you fix them.
Troubleshooting: If the plugin doesn't appear to work, check Settings → Tools → Compose Stability Analyzer and make sure Enable stability checks is turned on.
This JetBrains IDE plugin provides a Stability Explorer directly in your IDE, allowing you to visually trace which composable functions are skippable or non-skippable, and identify which parameters are stable or unstable within a specific package hierarchy.
You can enable this explorer with the steps below:
The Recomposition Cascade visualizer lets you trace the downstream impact of instability in your composable functions. Right-click any @Composable function in the editor and select "Analyze Recomposition Cascade" to see a tree of all downstream composables that would be affected by recomposition.
This helps you answer questions like:
The cascade tree shows:
The Live Recomposition Heatmap bridges runtime behavior with your IDE. It reads actual @TraceRecomposition events from a connected device via ADB logcat and overlays real recomposition counts directly above composable functions in the editor, color-coded by severity.
How to use:
@TraceRecomposition annotations to the composables you want to monitorComposeStabilityAnalyzer.setEnabled(BuildConfig.DEBUG) in your Application classColor-coded severity:
Click-to-inspect: Click on any recomposition count in the editor to open the Heatmap tab in the tool window, showing detailed recomposition event logs with parameter change history for that composable.
Note: The heatmap requires a connected device running your app with
@TraceRecompositioncomposables. Severity thresholds are configurable in Settings > Tools > Compose Stability Analyzer.
The Stability Reality Check answers a question the compiler can't: does the stability prediction actually hold up at runtime? Since Compose's strong skipping compares unstable parameters by instance identity (===), a parameter the compiler flags "unstable" often skips perfectly fine in practice — while another quietly recomposes on every frame. This feature joins the static prediction with live recomposition data and grades each parameter:
equals-equal but arrives as a , so strong skipping's check fails and it recomposes when it could have skipped. This is the real, hidden cost worth fixing (hoist the value into , or make the type stable).Grades appear in the editor inlay above each composable, in the hover tooltip (a "predicted vs. actual" column), and in the Reality tool-window tab as a module-wide scorecard with a "wasted recompositions" tally.
How to use:
@TraceRecomposition to the composables you want to grade, and enable ComposeStabilityAnalyzer.setEnabled(BuildConfig.DEBUG).Note: Grading relies on observed recompositions, so a parameter is graded only once its composable actually recomposes a few times. A stable parameter that simply skips is confirmed as expected and needs no attention.
The Recomposition Blame traces a recomposition back to its cause, in two complementary ways.
1. State write-site (runtime). For @TraceRecomposition(traceStates = true), a Compose Snapshot write observer records where each internal state was mutated and shows it inline in the log:
[state] counter: Int changed (0 → 1) ← onClick (MainActivity.kt:97)
The ← method (File.kt:line) tells you exactly which code wrote the state that triggered the recomposition — no more guessing.
2. Parameter provenance (static). Right-click any @Composable and choose "Blame this Recomposition":
A Blame tool-window tab opens showing the reverse of the cascade — which composables call this one, and where each argument's value originates (a val/var property, a parameter, a function call, …):
How to use:
@TraceRecomposition(traceStates = true), run the app, and read the ← … suffix on [state] lines in Logcat (or in the heatmap tooltip).Note: Write-site capture works for delegated scalar state (
var x by remember { mutableStateOf(...) }) on Android/JVM. Parameter provenance is a best-effort static estimate; dynamic origins are shown as "expression".
The Stability Doctor answers the question every other feature leads up to: "what should I fix first, and what will I gain?" It scans your project, scores every composable by combining the static stability verdict, the downstream cascade blast radius, and — when a heatmap session is running — the measured runtime waste from the Reality Check, then presents a ranked list of prescriptions with one-click fixes.
Each prescription shows:
How to use:
ESTIMATED scores, no device needed.@TraceRecomposition), start the recomposition heatmap, and interact with your app — rows upgrade to and re-rank automatically while the session runs.Note: Doctor thresholds (minimum score, cascade candidates, auto-refresh interval) are configurable in Settings → Tools → Compose Stability Analyzer → Stability Doctor.
You can change the colors used for stability indicators to match your IDE theme, enabling Strong Skipping mode for analyzing, visual indicators (showing gutter icons, warnings, inline hints), change parameter hint colors, enabling analysis in test source sets, set a stability configuration file, add ignored type patterns to exclude from the stability analysis.
You can change the configuration on the way below:
Settings → Tools → Compose Stability Analyzer
The Compose Stability Analyzer allows you to mark your own custom types as stable, even if they don't have @Stable or @Immutable annotations. This is useful when:
Setting up the configuration file:
Global settings (applies to all projects):
Per-project settings (recommended for teams):
config/stability-config.txt)Per-project settings take precedence over global settings. This means you can have:
You can track the recomposition for specific composable functions with the @TraceRecomposition annotation at runtime (KMP supports). You don't need to write any logging code yourself, just add the annotation, run your app, and watch detailed recomposition logs appear in Logcat. This compiler plugin supports Kotlin Multiplatform.
This is incredibly useful for:
@TraceRecomposition(threshold = 15)) and send a Firebase event or any custom analytics event to your cloud service to track which composable functions are experiencing excessive recompositions and examine the problems.Note: This library is completely independent of the Compose Stability Analyzer IntelliJ plugin and is entirely optional. You can choose to integrate it only if you find it suitable for your project.
First, add the plugin to the [plugins] section of your libs.versions.toml file:
stability-analyzer = { id = "com.github.skydoves.compose.stability.analyzer", version = "0.10.0" }
Then, apply it to your root build.gradle.kts with apply false:
alias(libs.plugins.stability.analyzer) apply false
Finally, apply the plugin to your app or shared module's build.gradle.kts:
alias(libs.plugins.stability.analyzer)
Sync your project to complete the setup.
It’s strongly recommended to use the exact same Kotlin version as this library. Using a different Kotlin version may lead to compilation errors during the build process.
Instead of annotating composables one by one, you can opt into trace-all mode, which auto-instruments every restartable composable in the module — as if each one carried @TraceRecomposition. This gives the IDE plugin's Live Heatmap, Reality Check, and Stability Doctor module-wide runtime data out of the box:
composeStabilityAnalyzer {
traceAll {
enabled.set(true) // default: false (opt-in)
threshold.set(2) // default: 2 — skips the initial-composition burst
variants.set(listOf("debug")) // default: ["debug"] — never applies to release or tests
}
}
How it behaves:
Logs from trace-all carry two extra header tokens — the fully qualified name and an auto marker — so the IDE can attribute events precisely even when composables share a simple name:
D/Recomposition: [Recomposition #2] UserProfile (1.20ms) (fq: com.example.profile.UserProfile) (auto)
@TraceRecomposition lets you trace the behavior of any composable function. By annotating a composable with @TraceRecomposition, you can log parameter changes whenever that function undergoes recomposition.
@TraceRecomposition
@Composable
fun UserProfile(user: User) {
Column {
Text("Name: ${user.name}")
Text("Age: ${user.age}")
}
}
That's it. When this composable recomposes, you'll see logs like:
D/Recomposition: ()
/: └─ : (User)
/: ()
/: └─ : (User → User)
The @TraceRecomposition annotation accepts two optional parameters to help you organize and filter logs:
threshold ParameterYou can configure the threshold parameter in the @TraceRecomposition annotation to log only when the recomposition count exceeds the specified threshold. This helps reduce noise from composables that frequently recompose. Additionally, you can use the recomposition callback for performance monitoring by sending custom events to Firebase or any other analytics platform.
@TraceRecomposition(threshold = 3)
@Composable
fun FrequentlyRecomposingScreen() {
// Will only start logging after the 3rd recomposition
}
Why thresholds matter
Many composables recompose 1-2 times during initial setup. These are expected and not performance issues. By using threshold = 3 or a specific number, you filter out the noise and focus on actual problems, composables that keep recomposing during user interaction.
The real example might be like so:
ComposeStabilityAnalyzer.setLogger(object : RecompositionLogger {
override fun log(event: RecompositionEvent) {
// Track excessive recompositions
if (event.recompositionCount >= 10) {
// Example: Send to Firebase Analytics
FirebaseAnalytics.getInstance().logEvent() {
param(, event.tag)
param(, event.composableName)
param(, event.recompositionCount)
param(, event.unstableParameters.joinToString())
}
}
}
})
tag parameter: filter your logsUse tags to categorize and filter your logs. Tags are especially useful when tracking multiple composables across different screens or features.
@TraceRecomposition(tag = "user-profile")
@Composable
fun UserProfile(user: User) {
// Your composable code
}
Now logs include the tag:
D/Recomposition: [Recomposition #1] UserProfile (tag: user-profile) (0.08ms)
D/Recomposition: └─ [param] user: User stable (User@abc123)
This is also very useful if you want to set a custom logger for ComposeStabilityAnalyzer, to distinguish which composable function should be examined like the example below:
val tagsToLog = setOf("user-profile", "checkout", "performance")
ComposeStabilityAnalyzer.setLogger(object : RecompositionLogger {
override fun log(event: RecompositionEvent) {
if (!BuildConfig.DEBUG) {
if (event.tag in tagsToLog || event.tag.isEmpty()) {
// Example: Send to Firebase Analytics only log events with specific tags
FirebaseAnalytics.getInstance(this).logEvent("excessive_recomposition") {
param("tag", event.tag)
param("composable", event.composableName)
param("count", event.recompositionCount)
param("unstable_params", event.unstableParameters.joinToString())
}
}
} else {
// Log everything on the debug mode
Log.d(..)
}
}
})
Filtering Logcat with tags
Once you have tags, you can filter Logcat to see only specific composables:
Recompositiontag: <tag name>UserProfile and RecompositionYou need to enable or disable the logging system in your app. Add this to your Application class:
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
// Enable recomposition tracking ONLY in debug builds
ComposeStabilityAnalyzer.setEnabled(BuildConfig.DEBUG)
}
}
Important Note
BuildConfig.DEBUG to avoid performance overhead in production or filter them clearly on the custom logger.ComposeStabilityAnalyzer, no logs will appear even with @TraceRecomposition.Also, you can completely redefine the logging behaviors by setting your custom logger like the example below:
Let's understand what each log tells you:
D/Recomposition: [Recomposition #1] UserProfile (0.12ms)
D/Recomposition: └─ [param] user: User stable (User@abc123)
What this means:
[Recomposition #1] - This is the first time this composable instance is recomposingUserProfile - The name of the composable functionuser: User - Parameter name and typestable - This parameter is stable(User@abc123) - The current value's identity (hashcode)This log confirms the composable is working correctly. The parameter is stable and the first recomposition is expected.
D/Recomposition: [Recomposition #2] UserProfile (0.15ms)
D/Recomposition: └─ [param] user: User changed (User@abc123 → User@def456)
What this means:
[Recomposition #2] - Second recompositionchanged - The parameter value changed (this is why it recomposed)(User@abc123 → User@def456) - Shows old value → new valueThis is normal behavior. The parameter changed, so the composable recomposed to show the new data. This is exactly what Compose should do.
D/Recomposition: [Recomposition #1] UserCard (tag: user-card) (0.25ms)
D/Recomposition: ├─ [param] user: MutableUser unstable (MutableUser@xyz789)
D/: └─ :
What this means
title: String stable - Not causing recompositioncount: Int changed (4 → 5) - This is why it recomposed (count changed from 4 to 5).items: List<Product> unstable - This list is unstable, causing unnecessary recompositions.Unstable parameters: [items] - Summary.Let's walk through a complete debugging session using @TraceRecomposition:
Problem: Your product list screen feels laggy. You suspect excessive recompositions.
Step 1: Add tracking
@TraceRecomposition(tag = "product-card", threshold = 3)
@Composable
fun ProductCard(
product: Product,
onClick: () -> Unit
) {
Card(onClick = onClick) {
Text(product.name)
Text("$${product.price}")
}
}
Step 2: Run your app and check Logcat
Step 3: Analyze
The logs reveal:
onClick is stable.product is unstable.ProductCard is recomposing 3+ times (that's why we see logs).Step 4: Check your Product class
// Current implementation (UNSTABLE)
data class Product(
var name: String, // ← var = mutable = unstable!
var price: Double // ← var = mutable = unstable!
)
Step 5: Fix it
// Fixed implementation (STABLE)
data class Product(
val name: String, // ← val = read-only = stable
val price: Double // ← val = read-only = stable
)
Step 6: Verify the fix
Run the app again and check Logcat:
D/Recomposition: [Recomposition #3] ProductCard (tag: product-card) (0.45ms)
D/Recomposition: ├─ : (Product)
/: └─ : () > (Function)
(No more excessive recompositions!)
By default, @TraceRecomposition only tracks parameter changes. When a composable recomposes due to internal state changes (mutableStateOf, derivedStateOf, etc.), the standard logs show nothing because the parameters haven't changed.
Setting traceStates = true enables internal state tracking:
@TraceRecomposition(traceStates = true)
@Composable
fun CounterScreen(title: String) {
var counter by remember { mutableIntStateOf(0) }
val doubled by remember { derivedStateOf { counter * 2 } }
Column {
Text(": (doubled: )")
Button(onClick = { counter++ }) {
Text()
}
}
}
After clicking the button:
D/Recomposition: [Recomposition #2] CounterScreen (1.20ms)
D/Recomposition: ├─ [param] title:
[]
[]
The [param] prefix identifies parameter entries, while [state] identifies internal state changes. Only states that actually changed are logged. This helps answer the question: "Why is this composable recomposing when parameters haven't changed?"
Note: State tracking detects delegated state properties (
var x by remember { mutableStateOf(...) }). Non-delegated patterns (val state = mutableStateOf(...)) are not tracked in the current version.
1. Don't track everything: Be selective about which composables you track. Focus on:
2. Use meaningful tags: Tags make filtering easier:
@TraceRecomposition(tag = "auth-flow") // Track entire feature
@TraceRecomposition(tag = "login-button") // Track specific component
3. Set appropriate thresholds: Reduce noise with thresholds:
@TraceRecomposition(threshold = 3) // Most common—skip initial setup
@TraceRecomposition(threshold = 10) // For very active composables
Imagine this scenario: You've spent weeks optimizing your app's Compose performance. All your composables are stable, skippable, and lightning-fast. Then someone on your team innocently changes a val to var in a data class, and suddenly dozens of composables become unstable. The performance regression slips through code review and makes it to production.
Stability Validation prevents this nightmare. It's like git diff for composable stability, it tracks your composables' stability over time and automatically fails your CI build if stability regresses. You can check out the quick integration codes.
Stability validation works through two Gradle tasks:
stabilityDump: Creates a snapshot of all composables' stability.stabilityCheck: Compares current stability against the snapshot.Think of it like this:
stabilityDump = "Save the current state"stabilityCheck = "Has anything changed since last save?"Note: Keep in mind that, all these Gradle tasks should be done after compile your project.
For Android projects, variant-specific tasks will be created, such as debugStabilityDump.
You can use those to only compile one variant of your module.
First, you need to generate a baseline—a snapshot of your current composables' stability.
Run this command:
./gradlew :app:stabilityDump
This creates a human-readable .stability file:
app/stability/app.stability
What's in this file?
It's a complete record of every composable in your module, showing:
The .stability file will be looking like below:
Each parameter is reported with one of four stability values, matching the Compose compiler:
This file is your stability contract. It says "these are all my composables, and this is how stable they should be."
Commit this file to git:
git add app/stability/app.stability
git commit -m "Add stability baseline for app module"
git push
Now everyone on your team has the same baseline. Any changes to composable stability will be detected!
The stabilityCheck task compares your current code against the baseline.
Run this command:
./gradlew :app:stabilityCheck
If nothing changed:
✅ Stability check passed.
Your composables' stability matches the baseline. Everything is good!
If stability regressed:
❌ Stability check failed!
The following composables have changed stability:
~ com.example.UserCard(user): stability changed from STABLE to UNSTABLE
If these changes are intentional, run './gradlew stabilityDump' to update the stability file.
The build fails, preventing the regression from being merged!
Types of changes detected
The task detects four types of changes:
Let's walk through a complete example:
data class User(val name: String, val age: Int)
@Composable
fun UserCard(user: User) {
Text("${user.name}, ${user.age}")
}
Generate baseline:
./gradlew :app:stabilityDump
git add app/stability/app.stability
git commit -m "Add stability baseline"
The .stability file now contains:
@Composable
public fun com.example.UserCard(user: com.example.User): kotlin.Unit
skippable: true
params:
- user: STABLE
If someone makes a change
A developer modifies the User class:
data class User(var name: String, var age: Int) // Changed val to var
They create a pull request. Your CI runs:
./gradlew :app:compileDebugKotlin
./gradlew :app:stabilityCheck
CI output:
❌ Stability check failed!
~ com.example.UserCard(user): stability changed from STABLE to UNSTABLE
If these changes are intentional, run './gradlew stabilityDump' to update the stability file.
The pull request cannot merge. The developer must either:
val.If the change is intentional
./gradlew :app:stabilityDump # Update baseline
git add app/stability/app.stability
git commit -m "Accept UserCard stability regression (justified by...)"
This creates a deliberate, documented decision in git history, rather than an accidental regression.
Add stability validation to your CI pipeline so it runs on every pull request:
GitHub Actions:
Now every pull request gets automatically checked for stability regressions!
You can customize what gets tracked and where files are stored in your Gradle file:
failOnStabilityChange OptionBy default, stabilityCheck will fail the build when stability changes are detected. This is ideal for CI/CD pipelines where you want to prevent stability regressions from being merged.
However, in some scenarios you may want to log warnings instead of failing:
composeStabilityAnalyzer {
stabilityValidation {
// Log stability changes as warnings instead of failing the build
failOnStabilityChange.set(false)
}
}
When to use failOnStabilityChange.set(false):
main branch.Example: Different behavior per environment
composeStabilityAnalyzer {
stabilityValidation {
// Fail on CI, warn locally
failOnStabilityChange.set(System.getenv("CI") == "true")
}
}
stabilityConfigurationFiles OptionYou can provide stability configuration files to tell stabilityCheck which types should be treated as stable, even if the compiler marks them as unstable. This matches the Compose compiler's stability configuration file format, so you can reuse the same file for both the compiler and stability validation.
This is useful when:
@Stable or @Immutable annotationscomposeStabilityAnalyzer {
stabilityValidation {
// Use the same stability configuration file as the Compose compiler
stabilityConfigurationFiles.add(
rootProject.layout.projectDirectory.file("stability_config.conf")
)
}
}
Example stability_config.conf:
// Types from third-party libraries
com.google.firebase.auth.FirebaseUser
com.squareup.moshi.JsonAdapter
// All types in a package
com.example.generated.*
// All types in a package and its sub-packages
com.example.models.**
The file supports * (single-level wildcard) and ** (multi-level wildcard) patterns. Lines starting with // are treated as comments.
When stabilityConfigurationFiles is set, the stabilityCheck task treats any parameter type matching these patterns as stable. This means:
Why ignore packages/classes
If you don't want to track:
These composables aren't in production, so their stability doesn't matter.
Sometimes you have composables that shouldn't be included in stability validation:
Use the @IgnoreStabilityReport annotation to exclude them:
@IgnoreStabilityReport
@Preview
@Composable
fun UserCardPreview() {
UserCard(user = User("John", 30))
}
This composable will be excluded from:
.stability files generated by stabilityDumpstabilityCheckFor projects with multiple modules, each module gets its own .stability file:
project/
├── app/
│ └── stability/
│ └── app.stability
├── feature-auth/
│ └── stability/
│ └── feature-auth.stability
└── feature-profile/
└── stability/
└── feature-profile.stability
Run stabilityCheck for all modules at once:
./gradlew stabilityCheck
Or check specific modules:
./gradlew :app:stabilityCheck
./gradlew :feature-auth:stabilityCheck
Support it by joining stargazers for this repository. :star:
Also follow me for my next creations! 🤩
Designed and developed by 2025 skydoves (Jaewoong Eum)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
@Composable function.← onClick (Screen.kt:42)) and where a parameter's value originated.===rememberESTIMATED (static analysis only) or MEASURED (backed by live device data — measured waste always outranks speculation).2 unstable params · ≈218ms observed waste (12 wasted recompositions) · 12 downstream affected.var → val on the parameter's class (aborts automatically if any write usage exists).@Immutable / @Stable.remember(keys) { ... } for silent waste parameters — offered only when a conservative set of safety rules proves the transformation safe, and always behind a preview/confirmation dialog.MEASURED| Stability Analyzer | Kotlin |
|---|
| 0.10.0 | 2.4.0 |
| 0.9.0 | 2.4.0 |
| 0.8.0 | 2.3.21 |
| 0.7.5 | 2.3.21 |
| 0.7.4 | 2.3.20 |
| 0.6.5~0.7.0 | 2.3.0 |
| 0.4.0~0.6.4 | 2.2.21 |
variants tokens are instrumented (debug matches debug, stagingDebug, ...). Test compilations are never instrumented. For KMP/JVM targets without variants, the runtime ComposeStabilityAnalyzer.setEnabled(...) gate is the safety net.@TraceRecomposition keeps its own tag/threshold.threshold = 2), so the initial composition of a screen produces no logcat flood. Raise the threshold if very active composables (e.g. animations) get noisy.@IgnoreStabilityReport, inline/readonly/non-restartable composables, and property getters are excluded automatically.ComposeStabilityAnalyzer.setEnabled(false), the residual cost per composition is a map lookup plus early-returned calls.ComposeStabilityAnalyzer.setLogger(object : RecompositionLogger {
override fun log(event: RecompositionEvent) {
val message = buildString {
append("🔄 Recomposition #${event.recompositionCount}")
append(" - ${event.composableName}")
if (event.tag.isNotEmpty()) {
append(" [${event.tag}]")
}
appendLine()
event.parameterChanges.forEach { change ->
append(" • ${change.name}: ${change.type}")
when {
change.changed -> append(" ➡️ CHANGED")
change.stable -> append(" ✅ STABLE")
else -> append(" ⚠️ UNSTABLE")
}
appendLine()
}
if (event.unstableParameters.isNotEmpty()) {
append(" ⚠️ Unstable: ${event.unstableParameters.joinToString()}")
}
}
Log.d("CustomRecomposition", message)
}
})
D/Recomposition: [Recomposition #5] ProductList (tag: products) (3.40ms)
D/Recomposition: ├─ [param] title: String stable (Products)
D/Recomposition: ├─ [param] count: Int changed (4 → 5)
D/Recomposition: ├─ [param] items: List<Product> unstable (List@abc)
D/Recomposition: └─ Unstable parameters: [items]
D/Recomposition: [Recomposition #3] ProductCard (tag: product-card) (0.45ms)
D/Recomposition: ├─ [param] product: Product unstable (Product@abc)
D/Recomposition: ├─ [param] onClick: () -> Unit stable (Function@xyz)
D/Recomposition: └─ Unstable parameters: [product]
D/Recomposition: [Recomposition #4] ProductCard (tag: product-card) (0.42ms)
D/Recomposition: ├─ [param] product: Product unstable (Product@abc)
D/Recomposition: ├─ [param] onClick: () -> Unit stable (Function@xyz)
D/Recomposition: └─ Unstable parameters: [product]
... (logs continue every scroll)
@Composable
public fun com.example.UserCard(user: com.example.User): kotlin.Unit
skippable: true
restartable: true
params:
- user: STABLE (marked @Stable or @Immutable)
@Composable
public fun com.example.ProductList(items: kotlin.collections.List<com.example.Product>): kotlin.Unit
skippable: true
restartable: true
params:
- items: STABLE (immutable collection with stable elements)
@Composable
public fun com.example.UnstableCard(user: com.example.MutableUser): kotlin.Unit
skippable: false
restartable: true
params:
- user: UNSTABLE (has mutable properties)
@Composable
public fun com.example.DetailScreen(repository: com.example.UserRepository): kotlin.Unit
skippable: false
restartable: true
params:
- repository: UNKNOWN (interface or non-final class; concrete implementation unknown)
| Value | Meaning |
|---|
STABLE | Known stable at compile time (skippable). |
UNSTABLE | Known unstable (e.g. has mutable var properties). |
RUNTIME | Stability depends on a runtime value (e.g. generic type parameters, standard collections). |
UNKNOWN | Cannot be determined statically because the concrete type is unknown — an interface or a non-final (open/abstract) class. Mirrors Compose 2.4.0, which infers Unknown for these by default. Like RUNTIME/UNSTABLE, a parameter with this value does not make a composable statically skippable. In stabilityCheck, a STABLE → UNKNOWN transition is reported as a regression. |
| Symbol | Change Type | Example |
|---|
~ | Stability regressed | Parameter changed from STABLE to UNSTABLE |
+ | New composable added | + com.example.NewScreen(title) |
- | Composable removed | - com.example.OldScreen(data) |
~ | Parameter count changed | Function signature changed |
name: Android CI
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up JDK 17
uses: actions/setup-java@v3
with:
java-version: '17'
distribution: 'temurin'
- name: Build project
run: ./gradlew :app:compileDebugKotlin
stability_check:
name: Compose Stability Check
runs-on: ubuntu-latest
needs: build <<<<< This is important
steps:
- name: Check out code
uses: actions/checkout@v5.0.0
- name: Set up JDK
uses: actions/setup-java@v5.0.0
with:
distribution: 'zulu'
java-version: 21
- name: compose stability check
run: ./gradlew stabilityCheck
// In your build.gradle.kts
composeStabilityAnalyzer {
stabilityValidation {
enabled.set(true) // Enable or disable stability validation
outputDir.set(layout.projectDirectory.dir("stability")) // set the output directory
includeTests.set(false) // Exclude test code from stability reports (default)
// Ignore specific packages or classes
ignoredPackages.set(listOf("com.example.internal"))
ignoredClasses.set(listOf("PreviewComposables"))
// Exclude specific sub-projects/modules (useful for multi-module projects)
ignoredProjects.set(listOf("benchmarks", "examples", "samples"))
// Control build failure behavior on stability changes (default: true)
failOnStabilityChange.set(true)
// Do not report any stable changes from the baseline (default: false)
ignoreNonRegressiveChanges.set(false)
// Allow the check to run, even if the baseline does not exist (default: false)
allowMissingBaseline.set(false)
// Allow the plugin to disable Kotlin incremental compilation when stability
// tasks run, so stability results stay accurate (default: true)
allowIncrementalDisabling.set(true)
// Add stability configuration file
// Matches compose's identical property
// (see https://developer.android.com/develop/ui/compose/performance/stability/fix#configuration-file)
stabilityConfigurationFiles.add(rootProject.layout.projectDirectory.file("stability_config.conf"))
}
}
Surfaced from shared tags and platforms — no rankings paid for.