You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+44-2Lines changed: 44 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,12 +40,14 @@ The sponsors listed below made it possible for this project to be released as op
40
40
41
41
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.
42
42
43
-
This plugin provides real-time visual feedback about your composables' stability through four main features:
43
+
This plugin provides real-time visual feedback about your composables' stability through six main features:
44
44
45
45
-**1. Gutter Icons**: Colored dots in the editor margin showing if a composable is skippable.
46
46
-**2. Hover Tooltips**: Detailed stability information when you hover over composable functions. It also provides the reasons: why it's stable or unstable.
47
47
-**3. Inline Parameter Hints**: Badges next to parameters showing their stability status.
48
48
-**4. Code Inspections**: Quick fixes and warnings for unstable composables.
49
+
-**5. Recomposition Cascade**: Visualize downstream composables affected by recomposition from any `@Composable` function.
50
+
-**6. Live Recomposition Heatmap**: Real-time recomposition counts from a connected device overlaid directly in the editor.
49
51
50
52
> **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](https://medium.com/proandroiddev/compose-stability-analyzer-real-time-stability-insights-for-jetpack-compose-1399924a0a64).
51
53
@@ -109,6 +111,46 @@ You can enable this explorer with the steps below:
109
111
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.
110
112
3. Clean & build your project, and click the refresh button on the panel.
111
113
114
+
### Recomposition Cascade
115
+
116
+
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.
117
+
118
+
119
+
120
+
This helps you answer questions like:
121
+
- "If this composable recomposes, how many downstream composables are affected?"
122
+
- "Which parts of my composable tree are skippable and which are not?"
123
+
- "Where should I focus my stability optimization efforts?"
124
+
125
+
The cascade tree shows:
126
+
- Each downstream composable with its stability status (skippable vs. non-skippable)
127
+
- Summary statistics: total downstream count, skippable count, unskippable count, and max depth
128
+
- Double-click any node to navigate directly to its source code
129
+
- Cycle detection and depth limits prevent infinite analysis in recursive call graphs
130
+
131
+
### Live Recomposition Heatmap
132
+
133
+
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.
134
+
135
+
136
+
137
+
**How to use:**
138
+
139
+
1. Add `@TraceRecomposition` annotations to the composables you want to monitor
140
+
2. Enable `ComposeStabilityAnalyzer.setEnabled(BuildConfig.DEBUG)` in your Application class
141
+
3. Connect your device/emulator and run the app
142
+
4. Click the **Start Recomposition Heatmap** button in the tool window title bar (or use **Code menu > Toggle Recomposition Heatmap**)
143
+
5. Interact with your app -- recomposition counts appear above composables in the editor in real time
144
+
145
+
**Color-coded severity:**
146
+
-**Green**: Low recomposition count (< 10 by default)
147
+
-**Yellow**: Medium recomposition count (10-50)
148
+
-**Red**: High recomposition count (50+)
149
+
150
+
**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.
151
+
152
+
> **Note**: The heatmap requires a connected device running your app with `@TraceRecomposition` composables. Severity thresholds are configurable in **Settings > Tools > Compose Stability Analyzer**.
153
+
112
154
### Plugin Customization
113
155
114
156
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.
@@ -170,7 +212,7 @@ This is incredibly useful for:
170
212
First, add the plugin to the `[plugins]` section of your `libs.versions.toml` file:
171
213
172
214
```toml
173
-
stability-analyzer = { id = "com.github.skydoves.compose.stability.analyzer", version = "0.6.7" }
215
+
stability-analyzer = { id = "com.github.skydoves.compose.stability.analyzer", version = "0.7.0" }
174
216
```
175
217
176
218
Then, apply it to your root `build.gradle.kts` with `apply false`:
Copy file name to clipboardExpand all lines: compose-stability-analyzer-idea/build.gradle.kts
+19Lines changed: 19 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -71,6 +71,25 @@ intellijPlatform {
71
71
</ul>
72
72
""".trimIndent()
73
73
changeNotes ="""
74
+
<b>0.7.0</b>
75
+
<ul>
76
+
<li><b>New: Recomposition Cascade Visualizer</b> - Right-click any @Composable function to trace downstream composables affected by recomposition. Shows a tree view with stability status, summary statistics, cycle detection, and source navigation.</li>
77
+
<li><b>New: Live Recomposition Heatmap</b> - Real-time recomposition counts from a connected device overlaid directly above composable functions in the editor. Color-coded by severity (green/yellow/red). Click any count to view detailed event logs with parameter change history.</li>
78
+
<li><b>New: Heatmap tab</b> in tool window - Shows recomposition event logs with parameter changes when clicking heatmap counts</li>
79
+
<li><b>New: Cascade tab</b> in tool window - Dedicated panel for cascade analysis results</li>
80
+
<li>Start/Stop Heatmap button moved to tool window title bar for easy access across all tabs</li>
81
+
<li>Extended IDE compatibility to build 261 (IntelliJ IDEA 2026.1)</li>
82
+
<li>Heatmap enabled by default in plugin settings</li>
83
+
</ul>
84
+
<b>0.6.7</b>
85
+
<ul>
86
+
<li><b>Android variant-specific stability tasks</b> (Issue #85) - Per-variant tasks like debugStabilityDump and releaseStabilityCheck</li>
87
+
<li><b>Non-regressive change filtering</b> (Issue #82) - New ignoreNonRegressiveChanges and allowMissingBaseline options</li>
88
+
<li><b>Stability config wildcard support</b> (Issue #108) - Support for * and ** wildcards matching the official Compose compiler format</li>
89
+
<li><b>Fixed @StabilityInferred in Gradle plugin</b> (Issue #102) - Cross-module classes now correctly treated as stable</li>
90
+
<li><b>Fixed @NonRestartableComposable/@NonSkippableComposable analysis</b> (Issue #103) - Now excluded from stability analysis</li>
91
+
<li><b>Improved typealias handling</b> (Issue #16) - Typealias to function types now correctly recognized as stable</li>
92
+
</ul>
74
93
<b>0.6.2</b>
75
94
<ul>
76
95
<li><b>Fixed property source file location and navigation in tool window</b> (Issue #67) - Properties now show correct file name and double-click navigation works</li>
Copy file name to clipboardExpand all lines: docs/ide-plugin/getting-started.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,7 @@ The plugin requires **Android Studio or IntelliJ IDEA 2024.2+** (build 242 or la
16
16
17
17
## What You'll See
18
18
19
-
Once installed, the plugin provides four types of visual feedback that work together to give you a complete picture of your composables' stability.
19
+
Once installed, the plugin provides six types of visual feedback that work together to give you a complete picture of your composables' stability.
20
20
21
21
**Gutter Icons** are colored dots that appear in the left margin of your editor. Green means the composable is skippable (all parameters stable), yellow means stability is determined at runtime, and red means the composable has unstable parameters and cannot be skipped. This is the quickest way to scan your code for potential performance issues.
22
22
@@ -26,6 +26,10 @@ Once installed, the plugin provides four types of visual feedback that work toge
26
26
27
27
**Code Inspections** go beyond passive indicators. When a composable has unstable parameters, the plugin highlights the issue with a warning underline and offers quick fixes through the Alt+Enter menu, such as adding `@TraceRecomposition` for runtime debugging.
28
28
29
+
**[Recomposition Cascade](recomposition-cascade.md)** lets you trace the downstream impact of recomposition. Right-click any composable and select "Analyze Recomposition Cascade" to see a tree of all child composables that would be affected, with stability status for each one.
30
+
31
+
**[Live Recomposition Heatmap](recomposition-heatmap.md)** bridges runtime behavior with your IDE by displaying actual recomposition counts from a connected device directly above composable functions in the editor. Color-coded annotations (green, yellow, red) highlight the hottest spots in your UI in real time.
32
+
29
33
## Verification
30
34
31
35
To verify the plugin is working, open any Kotlin file with `@Composable` functions and look for colored dots in the left margin (the gutter area). Hover over a composable function name; you should see a tooltip with detailed stability information. If nothing appears, the plugin may be disabled.
The Recomposition Cascade Visualizer lets you trace the downstream impact of a composable's recomposition. Starting from any `@Composable` function, it analyzes the call tree to show which child composables would be affected when the parent recomposes, along with each one's stability status. This helps you understand the ripple effect of a single unstable composable across your UI hierarchy.
Right-click any `@Composable` function in the editor and select **Analyze Recomposition Cascade** from the context menu. The plugin performs a background analysis of the function's call tree and displays the results in the **Cascade** tab of the Compose Stability Analyzer tool window.
10
+
11
+
The analysis runs in the background with cancellation support, so you can continue working in the editor while it processes. For large call trees, a progress indicator shows the current analysis status.
12
+
13
+
## Tree View
14
+
15
+
The results appear as a hierarchical tree rooted at the composable you selected. Each node represents a downstream composable that the root calls, directly or transitively. Nodes are nested to reflect the actual call structure: if `ScreenA` calls `Header` which calls `Title`, the tree shows `ScreenA` > `Header` > `Title`.
16
+
17
+
Each node displays the composable's name and its stability status. **Skippable** composables appear with a green indicator, meaning all their parameters are stable and Compose can skip them during recomposition. **Non-skippable** composables appear with a red indicator, meaning they have at least one unstable parameter and will always re-execute when their parent recomposes.
18
+
19
+
## Summary Statistics
20
+
21
+
At the top of the cascade tree, a summary node shows aggregate statistics for the entire call tree: the total number of downstream composables found, how many are skippable, how many are non-skippable, and the maximum depth of the tree. This gives you a quick sense of the blast radius. A root composable with 15 downstream composables and 8 of them non-skippable has a much larger performance impact than one with 3 downstream composables that are all skippable.
22
+
23
+
## Cycle Detection
24
+
25
+
Compose UIs can have recursive or mutually recursive composable calls (for example, a tree-rendering composable that calls itself for child nodes). The cascade analyzer detects these cycles and marks them in the tree rather than entering an infinite loop. When a cycle is detected, the node shows a cycle indicator and stops expanding further along that path.
26
+
27
+
The analysis also enforces a configurable maximum depth limit (default: 10 levels) to keep results manageable and prevent excessively deep trees from slowing down the analysis.
28
+
29
+
## Navigation
30
+
31
+
Double-clicking any node in the cascade tree navigates directly to that composable's source code in the editor. This makes the cascade view an effective tool for tracing performance issues through your UI hierarchy: spot a non-skippable composable deep in the tree, double-click to jump to its source, and investigate why its parameters are unstable.
32
+
33
+
## Practical Workflow
34
+
35
+
The cascade visualizer is most useful when you've identified a composable with performance issues and want to understand the full impact. For example, if your main screen composable recomposes frequently, running a cascade analysis shows you every downstream composable that gets affected. You might discover that a single unstable data class parameter at the root causes dozens of child composables to re-execute unnecessarily.
36
+
37
+
Start by analyzing high-level screen composables to get a broad view of your recomposition impact. Focus on branches where non-skippable composables cluster together, as these represent the highest-impact areas for optimization. After fixing stability issues, re-run the cascade analysis to confirm that the downstream composables are now skippable.
0 commit comments