skydoves/compose-stability-analyzer

Compose Stability Analyzer

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.

💝 Sponsors

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 Book

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.

Compose Stability Analyzer Plugin

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:

• 1. Gutter Icons: Colored dots in the editor margin showing if a composable is skippable.
• 2. Hover Tooltips: Detailed stability information when you hover over composable functions. It also provides the reasons: why it's stable or unstable.
• 3. Inline Parameter Hints: Badges next to parameters showing their stability status.
• 4. Code Inspections: Quick fixes and warnings for unstable composables.
• 5. Recomposition Cascade: Visualize downstream composables affected by recomposition from any @Composable function.
• 6. Live Recomposition Heatmap: Real-time recomposition counts from a connected device overlaid directly in the editor.
• 7. Stability Reality Check: Grades the compiler's static stability prediction against live runtime data, separating harmless false alarms from real "silent waste".
• 8. Recomposition Blame: Traces a recomposition back to its cause — the exact state write-site (← onClick (Screen.kt:42)) and where a parameter's value originated.
• 9. Stability Doctor: A ranked, quantified "what to fix first" list that combines all of the above — static verdicts, blast radius, and measured runtime waste — into prioritized prescriptions with one-click fixes.

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.

How to Install in Android Studio

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.

Stability Mark for Composable Functions

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:

• Whether it's skippable or restartable
• How many parameters are stable vs. unstable
• Which specific parameters are causing instability
• Additional context about receivers (if any)

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 Parameter Hints

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

Code inspections go beyond visual indicators, they actively suggest improvements. When you have an unstable composable, the plugin can:

1. Highlight the issue with a warning underline
2. Suggest quick fixes via Alt+Enter menu
3. Add @TraceRecomposition to help you debug recompositions
4. Provide suppression options if the instability is intentional

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.

Stability Explorer

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:

1. Install the Compose Stability Analyzer Gradle plugin
2. On your IDE, go to View -> Tool Windows -> Compose Stability Analyzer, then you will see the icon on the right side of your Android Studio. Click the icon then you'll see a panel.
3. Clean & build your project, and click the refresh button on the panel.

Recomposition Cascade

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:

• "If this composable recomposes, how many downstream composables are affected?"
• "Which parts of my composable tree are skippable and which are not?"
• "Where should I focus my stability optimization efforts?"

The cascade tree shows:

• Each downstream composable with its stability status (skippable vs. non-skippable)
• Summary statistics: total downstream count, skippable count, unskippable count, and max depth
• Double-click any node to navigate directly to its source code
• Cycle detection and depth limits prevent infinite analysis in recursive call graphs

Live Recomposition Heatmap

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:

1. Add @TraceRecomposition annotations to the composables you want to monitor
2. Enable ComposeStabilityAnalyzer.setEnabled(BuildConfig.DEBUG) in your Application class
3. Connect your device/emulator and run the app
4. Click the Start Recomposition Heatmap button in the tool window title bar (or use Code menu > Toggle Recomposition Heatmap)
5. Interact with your app -- recomposition counts appear above composables in the editor in real time

Color-coded severity:

• Green: Low recomposition count (< 10 by default)
• Yellow: Medium recomposition count (10-50)
• Red: High recomposition count (50+)

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 @TraceRecomposition composables. Severity thresholds are configurable in Settings > Tools > Compose Stability Analyzer.

Stability Reality Check

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:

• 🟢 Confirmed: the prediction held — stable and not wastefully recomposing.
• 🟡 False alarm: predicted unstable, but the instance stays referentially stable at runtime, so Compose skips it fine. You can safely ignore the warning.
• 🔴 Silent waste: the value is equals-equal but arrives as a new instance every recomposition, 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 remember, 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:

1. Add @TraceRecomposition to the composables you want to grade, and enable ComposeStabilityAnalyzer.setEnabled(BuildConfig.DEBUG).
2. Start the recomposition heatmap (Reality Check shares the same live data) and interact with your app.
3. Hover a composable or open the Reality tab — grades appear after a few observed recompositions.

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.

Recomposition Blame

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:

• Write-sites: add @TraceRecomposition(traceStates = true), run the app, and read the ← … suffix on [state] lines in Logcat (or in the heatmap tooltip).
• Provenance: right-click a composable in the editor → Blame this Recomposition → inspect the upstream tree (works statically, no device needed).

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".

Stability Doctor

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:

• A score badge: ESTIMATED (static analysis only) or MEASURED (backed by live device data — measured waste always outranks speculation).
• A problem summary: e.g. 2 unstable params · ≈218ms observed waste (12 wasted recompositions) · 12 downstream affected.
• Causes: each problematic parameter with its static reason, Reality-Check grade, and where the value comes from (via Blame).
• Fixes you can apply by double-clicking:
  • Change var → val on the parameter's class (aborts automatically if any write usage exists).
  • Annotate the class with @Immutable / @Stable.
  • Add the type to your stability configuration file (for library types).
  • Wrap the call-site argument in 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.

How to use:

1. Open View → Tool Windows → Compose Stability Analyzer → Doctor tab (or Code menu → Run Stability Doctor) and hit refresh — works immediately with ESTIMATED scores, no device needed.
2. For measured scores, enable trace-all (or annotate composables with @TraceRecomposition), start the recomposition heatmap, and interact with your app — rows upgrade to MEASURED and re-rank automatically while the session runs.
3. Double-click a row to jump to the composable; double-click a fix to apply it.

Note: Doctor thresholds (minimum score, cascade candidates, auto-refresh interval) are configurable in Settings → Tools → Compose Stability Analyzer → Stability Doctor.

Plugin Customization

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

Stability Configuration File

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:

• You have immutable data classes from third-party libraries that aren't annotated
• You're using code generation tools that produce stable types
• You want to treat certain types as stable without modifying their source code
• You have legacy code that you know is stable but can't easily refactor

Setting up the configuration file:

Global settings (applies to all projects):

1. Create your configuration file anywhere on your system
2. Go to Settings → Tools → Compose Stability Analyzer
3. Scroll to "Ignored Type Patterns" and add your patterns directly
4. Or reference a file path in the "Stability configuration file" field (global)

Per-project settings (recommended for teams):

1. Create a configuration file in your project (e.g., config/stability-config.txt)
2. Go to Settings → Tools → Compose Stability Analyzer → Project Configuration
3. Set the path to your configuration file
4. Commit the file to version control so your team shares the same configuration

Per-project settings take precedence over global settings. This means you can have:

• Global settings for your personal preferences
• Project-specific settings that your entire team uses

Gradle Plugin for Tracking Runtime Recomposition and Stability Validation

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 is incredibly useful for:

• Debugging performance issues: Find out which composables recompose too often, and why it was happen.
• Monitor stability performance: Set a threshold (@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.
• Understanding Compose behavior: Learn how state changes trigger recompositions.
• Validating optimizations: Confirm your stability fixes actually work.

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.

Including in 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.12.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.

Kotlin Version Mapping

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.

Kotlin Multiplatform Support

The compiler plugin runs on every Kotlin compilation in your module, and the runtime is published for these targets:

Apply the plugin to your shared module and it adds the runtime to commonMain for you. Stability analysis, @TraceRecomposition parameter tracing, tags, thresholds, timing and internal state changes work on all of the targets above. Two things are Android or JVM only: the ← onClick (Screen.kt:42) write-site suffix on [state] lines needs Compose's Snapshot write observer, and the IDE plugin's live Heatmap, Reality Check and measured Doctor scores read logs from a device over ADB. Everything the IDE derives statically works for any target.

watchOS, tvOS, Android Native and wasmWasi are not published yet, so open an issue if you need one.

See the Kotlin Multiplatform guide for the full breakdown, including where logs go per target, how trace-all behaves without build variants, and how stabilityDump works in a multiplatform module.

Trace-All: Module-Wide Recomposition Tracing

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:

• Debug-oriented by default: only compilations whose variant name ends with one of the 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.
• Explicit annotations win: a composable with @TraceRecomposition keeps its own tag/threshold.
• Quiet by default: auto-traced composables only start logging from their 2nd recomposition (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.
• Skips what shouldn't be traced: previews, @IgnoreStabilityReport, inline/readonly/non-restartable composables, and property getters are excluded automatically.
• Cheap when disabled: with ComposeStabilityAnalyzer.setEnabled(false), the residual cost per composition is a map lookup plus early-returned calls.

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 Annotation

@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: [Recomposition #1] UserProfile (0.12ms)
D/Recomposition:   └─ [param] user: User stable (User@abc123)
D/Recomposition: [Recomposition #2] UserProfile (0.15ms)
D/Recomposition:   └─ [param] user: User changed (User@abc123 → User@def456)

Annotation Parameters

The @TraceRecomposition annotation accepts two optional parameters to help you organize and filter logs:

The threshold Parameter

You 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(this).logEvent("excessive_recomposition") {
        param("tag", event.tag)
        param("composable", event.composableName)
        param("count", event.recompositionCount)
        param("unstable_params", event.unstableParameters.joinToString())
      }
    }
  }
})

The tag parameter: filter your logs

Use 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:

• See all recompositions: Filter by Recomposition
• See a tagged recompositions: Filter by tag: <tag name>
• See specific composable: Filter by UserProfile and Recomposition

Configure Custom Logger & Enable Logging

You 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

• Always wrap with BuildConfig.DEBUG to avoid performance overhead in production or filter them clearly on the custom logger.
• If you don't enable ComposeStabilityAnalyzer, no logs will appear even with @TraceRecomposition.
• This logging has minimal performance impact in debug builds but should still be disabled in release builds for any security reasons of your app.

Also, you can completely redefine the logging behaviors by setting your custom logger like the example below:

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)
  }
})

Reading the Logs

Let's understand what each log tells you:

First Recomposition

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 recomposing
• UserProfile - The name of the composable function
• user: User - Parameter name and type
• stable - 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.

Parameter Changed

D/Recomposition: [Recomposition #2] UserProfile (0.15ms)
D/Recomposition:   └─ [param] user: User changed (User@abc123 → User@def456)

What this means:

• [Recomposition #2] - Second recomposition
• changed - The parameter value changed (this is why it recomposed)
• (User@abc123 → User@def456) - Shows old value → new value

This is normal behavior. The parameter changed, so the composable recomposed to show the new data. This is exactly what Compose should do.

Unstable Parameter

D/Recomposition: [Recomposition #1] UserCard (tag: user-card) (0.25ms)
D/Recomposition:   ├─ [param] user: MutableUser unstable (MutableUser@xyz789)
D/Recomposition:   └─ Unstable parameters: [user]

Multiple Parameters (Mixed Stability)

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]

What this means

• title: String stable - Not causing recomposition
• count: 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.

Real-World Example

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

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)

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:   ├─ [param] product: Product stable (Product@abc)
D/Recomposition:   └─ [param] onClick: () -> Unit stable (Function@xyz)

(No more excessive recompositions!)

Internal State Tracking

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("$title: $counter (doubled: $doubled)")
        Button(onClick = { counter++ }) {
            Text("Increment")
        }
    }
}

After clicking the button:

D/Recomposition: [Recomposition #2] CounterScreen (1.20ms)
D/Recomposition:   ├─ [param] title: String stable (Counter)
D/Recomposition:   ├─ [state] counter: Int changed (0 → 1)
D/Recomposition:   └─ State changes: [counter]

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.

Best Practices

1. Don't track everything: Be selective about which composables you track. Focus on:

• Composables you suspect have performance issues.
• List items (they recompose frequently).
• Complex screens with many parameters.

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

Stability Validation

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.

How It Works

Stability validation works through two Gradle tasks:

1. stabilityDump: Creates a snapshot of all composables' stability.
2. 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.

Android

For Android projects, variant-specific tasks will be created, such as debugStabilityDump. You can use those to only compile one variant of your module.

Step 1: Create a Stability Baseline

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:

• Function signature (name, parameters, return type)
• Whether it's skippable and restartable
• Stability of each parameter

The .stability file will be looking like below:

@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)

@Composable
public fun com.example.rememberUserState(user: com.example.User): com.example.UserState
  skippable: false
  restartable: false
  params:
    - user: STABLE (marked @Stable or @Immutable)

Skippable vs. restartable. A composable is restartable only when the Compose compiler wraps it in a restart group. It does not for @NonRestartableComposable, @ReadOnlyComposable, or @ExplicitGroupsComposable composables, inline functions, or composables that return a non-Unit value (such as rememberUserState above). A non-restartable composable can never be skippable, regardless of how stable its parameters are. @NonSkippableComposable is the exception that stays restartable but opts out of skipping (skippable: false, restartable: true). In stabilityCheck, both a skippable and a restartable true → false transition are reported as regressions.

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!

Step 2: Check for Stability Changes

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:

Real-World Example

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:

1. Fix the regression - Change back to val.
2. Update the baseline - If the change is intentional.

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.

CI/CD Integration

Add stability validation to your CI pipeline so it runs on every pull request:

GitHub Actions:

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/[email protected]
      - name: Set up JDK
        uses: actions/[email protected]
        with:
          distribution: 'zulu'
          java-version: 21
      - name: compose stability check
        run: ./gradlew stabilityCheck    

Now every pull request gets automatically checked for stability regressions!

Configuration

You can customize what gets tracked and where files are stored in your Gradle file:

// 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"))
    }
}

failOnStabilityChange Option

By 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):

• Initial adoption: When first adding stability validation to an existing project, you may want to see all stability issues without blocking builds.
• Gradual migration: Allow the team to fix stability issues incrementally while still tracking them.
• Development branches: Use warnings during development, but enable strict mode for main branch.
• Monitoring only: Track stability trends without enforcing them as build requirements.

Example: Different behavior per environment

composeStabilityAnalyzer {
    stabilityValidation {
        // Fail on CI, warn locally
        failOnStabilityChange.set(System.getenv("CI") == "true")
    }
}

stabilityConfigurationFiles Option

You 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:

• Third-party library types don't have @Stable or @Immutable annotations
• Code-generated types are effectively stable but the compiler can't infer it
• You want the stability check to respect the same overrides as the Compose compiler

composeStabilityAnalyzer {
    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:

• New composables with all parameters matching these patterns won't be flagged
• Parameter stability changes from UNSTABLE to a matching type won't be reported as regressions

Why ignore packages/classes

If you don't want to track:

• Preview composables (only used in Android Studio previews)
• Test composables (only used in UI tests)
• Debug screens (only in debug builds)

These composables aren't in production, so their stability doesn't matter.

Excluding Composables from Reports

Sometimes you have composables that shouldn't be included in stability validation:

• Preview composables: Only used for Android Studio previews.
• Debug/test composables: Only in debug builds.
• Experimental composables: Still under development.

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 stabilityDump
• Stability validation checks by stabilityCheck

Multi-Module Projects

For 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

Find this library useful? :heart:

Support it by joining stargazers for this repository. :star:
Also follow me for my next creations! 🤩

License

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.