santimattius/performance-compose-skills/compose-previews-tooling

Performance First

Every Compose frame runs three phases. Cost rises left-to-right; restart scope shrinks left-to-right.

Defer State Reads (decision tree)

Do you need the value during composition?

• YES → read as T (Composition phase) — accept full restart cost
• NO → can you defer to layout/draw?
• Layout-only? → pass () -> T into Modifier.layout/offset { } lambda
• Draw/transform? → pass () -> T into Modifier.graphicsLayer { } / drawBehind { } lambda

Rule: prefer Modifier.offset { lambda } over Modifier.offset(state.value.dp). Lambda variant defers the read to the layout phase, skipping recomposition entirely.

Profile-in-Release Mandate

CRITICAL: Previews run in the same JVM/LayoutLib environment as debug builds — they do NOT reflect release performance. Debug and preview environments disable R8, inlining, and Strong Skipping Mode, making ALL numbers meaningless for performance. NEVER use debug builds or Previews as a performance baseline. Always profile a release or benchmark build type on a real device.

// ❌ WRONG: profiling debug build numbers
./gradlew assembleDebug  // measurements here are invalid
 
// ✅ CORRECT: always profile release or benchmark
./gradlew assembleBenchmark  // or assembleRelease with profileable=true

Performance Toolchain

WARNING: NEVER profile in debug builds. Debug disables R8, inlining, and Strong Skipping — numbers are meaningless. Always profile a release build with profileable enabled or a benchmark build type.

When to Use

Use this skill when:

• Writing or configuring @Preview for a composable
• Wrapping all previews with a custom theme using @PreviewWrapper
• Creating data-driven previews with @PreviewParameter
• Deciding between screenshot testing libraries (Paparazzi vs Roborazzi vs instrumented)
• Enabling or interpreting Compose Compiler Reports (stability analysis)
• Adding Composition Tracing to diagnose frame-timing problems
• Setting up Layout Inspector for recomposition count debugging
• Configuring Macrobenchmark for performance regression gates

CMP Applicability

Canonical CMP rules: `../_shared/cmp-platform.md`

Status legend: ✅ fully supported · ⚠️ partial / version-gated · ❌ Android-only.

Android-only tools (do NOT suggest for CMP non-Android targets):

• Paparazzi — Android/JVM renderer only
• Macrobenchmark — requires Android device/emulator
• Baseline Profiles — AGP + Android only
• Layout Inspector — Android Studio only

CMP-compatible tools: JetBrains @Preview (CMP 1.5+, Fleet/IJ), Compose Hot Reload (experimental), runComposeUiTest (commonTest), Compose Compiler Reports (all targets), Roborazzi ⚠️ (1.7+, Android JVM runner).

See full tooling matrix: `references/cmp-tooling-matrix.md`.

Critical Patterns

1. @PreviewWrapper + PreviewWrapperProvider — New April 2026

NEW April 2026 — NOT in pre-2026 docs: @PreviewWrapper was introduced in April 2026. Do not expect it in documentation predating this date.

@PreviewWrapper lets you define a single composable wrapper that is automatically applied to ALL @Preview annotations in the module. This eliminates the need to manually wrap every preview with your theme.

// Step 1: Define the wrapper
class AppThemePreviewWrapper : PreviewWrapperProvider {
    @Composable
    override fun PreviewWrapper(content: @Composable () -> Unit) {
        AppTheme(darkTheme = false) {
            Surface { content() }
        }
    }
}
 
// Step 2: Register it (in your module's build.gradle.kts or via @PreviewWrapper annotation)
@PreviewWrapper(AppThemePreviewWrapper::class)
annotation class AppPreview
 
// Step 3: Use it — the wrapper is applied automatically
@AppPreview
@Composable
fun MyButtonPreview() {
    MyButton(text = "Save", onClick = {})
}

Without @PreviewWrapper, every preview file manually wraps content in the theme, causing drift when the theme signature changes.

2. @PreviewParameter — Data-Driven Previews

@PreviewParameter generates one preview instance per value in the provider, covering multiple states automatically.

class UserStateProvider : PreviewParameterProvider<UserState> {
    override val values = sequenceOf(
        UserState.Loading,
        UserState.Success(name = "Jane Doe"),
        UserState.Error(message = "Network timeout"),
    )
}
 
@Preview
@Composable
fun UserCardPreview(
    @PreviewParameter(UserStateProvider::class) state: UserState
) {
    UserCard(state = state)
}

Decision: use @PreviewParameter for components with distinct state variants (loading/success/error). Do NOT use it for exhaustive enum coverage that would produce >10 previews — that degrades IDE performance.

3. Screenshot Testing — ALPHA Warning

ALPHA — Screenshot Testing Activity (androidx.compose.ui.test.screenshot): 0.0.1-alpha14: API may break between releases. Requires AGP 8.5+ for full functionality; AGP 9.0+ for IDE integration. Prefer Paparazzi or Roborazzi for production CI pipelines.

// Stable alternatives (NOT alpha):
// Paparazzi: JVM-based, no emulator needed, fast CI feedback
// Roborazzi: Robolectric-based, closer to Android runtime, strong diff reports
// Shot: instrumentation-based, real Android runtime, slower
// Dropshots: instrumentation-based, in-test comparison

Decision tree for screenshot library:

Do you need a real Android runtime?
├── YES → Shot or Dropshots (instrumentation-based, real device/emulator)
└── NO  → Do you already use Robolectric?
          ├── YES → Roborazzi (natural fit, strong diffs)
          └── NO  → Paparazzi (fast, LayoutLib-based, simplest setup)

4. Profile-in-Release Mandate

Debug builds disable:

• R8 optimization (code shrinking + inlining)
• Strong Skipping Mode (all lambdas treated as unstable)
• Compose Compiler optimizations

Result: any performance number from a debug build is meaningless for production decisions. Configure benchmark build type:

// build.gradle.kts — benchmark build type
buildTypes {
    create("benchmark") {
        initWith(getByName("release"))
        signingConfig = signingConfigs.getByName("debug")
        matchingFallbacks += listOf("release")
        isDebuggable = false
    }
}

5. Compose Compiler Reports

Reports show stability status of every composable's parameters. Run ONLY on release/benchmark builds.

// build.gradle.kts
composeCompiler {
    reportsDestination = layout.buildDirectory.dir("compose_compiler")
    metricsDestination = layout.buildDirectory.dir("compose_compiler")
}

Interpret the output:

• restartable — composable can skip if inputs unchanged (good)
• skippable — composable WILL skip on recomposition if stable inputs unchanged (best)
• unstable — composable ALWAYS recomposes (investigate)

# Generate reports
./gradlew assembleRelease
 
# Find new unstable types introduced in a PR (CI gate)
grep "unstable" build/compose_compiler/*-classes.txt

6. Composition Tracing — ProGuard Rule for Release

Composition Tracing inserts trace markers for Android Studio's CPU Profiler. These markers must NOT be stripped by R8 in release builds.

# Keep composition tracing markers in release
-keep class androidx.compose.runtime.CompositionTracing { *; }
-keepclassmembers class ** {
    @androidx.compose.runtime.Composable <methods>;
}

Add the runtime-tracing artifact:

// libs.versions.toml
compose-runtime-tracing = { group = "androidx.compose.runtime", name = "runtime-tracing", version = "..." }

7. Layout Inspector Requirements

• Android device/emulator: API 29+
• Compose: 1.2+
• Enable: View > Tool Windows > Layout Inspector in Android Studio

Use it to inspect:

• Recomposition counts per composable (shows which ones fire excessively)
• Semantics tree (for accessibility debugging)
• Layer hierarchy and modifier chains

Pitfalls

Code Examples

Full Preview Setup with @PreviewWrapper

// ThemePreviewWrapper.kt
class AppThemeWrapper : PreviewWrapperProvider {
    @Composable
    override fun PreviewWrapper(content: @Composable () -> Unit) {
        MaterialTheme { Surface(color = MaterialTheme.colorScheme.background) { content() } }
    }
}
 
@PreviewWrapper(AppThemeWrapper::class)
@Preview(showBackground = true)
annotation class AppPreview
 
@PreviewWrapper(AppThemeWrapper::class)
@Preview(showBackground = true, uiMode = UI_MODE_NIGHT_YES)
annotation class AppPreviewDark
 
// Usage
@AppPreview
@AppPreviewDark
@Composable
fun PrimaryButtonPreview() {
    PrimaryButton(text = "Confirm", onClick = {})
}

Paparazzi Screenshot Test

@RunWith(JUnit4::class)
class MyButtonScreenshotTest {
    @get:Rule
    val paparazzi = Paparazzi(
        deviceConfig = DeviceConfig.PIXEL_6,
    )
 
    @Test
    fun button_defaultState() {
        paparazzi.snapshot {
            MyButton(text = "Save", onClick = {})
        }
    }
}

Commands

# Generate Compose Compiler Reports (release only)
./gradlew assembleRelease
 
# Check for unstable composables in CI
grep "unstable" app/build/compose_compiler/*-classes.txt
 
# Record Paparazzi baselines
./gradlew recordPaparazziDebug
 
# Verify Paparazzi screenshots in CI
./gradlew verifyPaparazziDebug
 
# Record Roborazzi baselines
./gradlew recordRoborazziDebug

Related Skills