flutter-performance-profiling

Flutter Performance Profiling

Overview

The Flutter Performance Profiling skill delivers rigorous diagnosis, instrumentation, and remediation workflows for Flutter runtime performance issues. Compatible across Claude Code and Google Antigravity, this skill guides developers to profile before optimizing—distinguishing UI thread bottlenecks (expensive widget trees, redundant layout computations) from raster thread stalls (shader warmup jank, excessive layer clipping, overdraw, expensive saveLayer calls) to ensure smooth 60fps / 120fps frame rates.

When to Use

Trigger Scenarios

• Investigating frame drops, stutter, or jank during scrolling and route transitions.
• Profiling and reducing cold/warm app startup latency.
• Diagnosing memory leaks, image bloat, or climbing heap allocations over extended sessions.
• Pre-release performance qualification for production releases.

When NOT to Use

• Layout overflow bugs: For layout constraint violations and overflow render errors, use flutter-fix-layout-issues.
• Backend or network latency: For slow API queries or backend database bottlenecks, use performance-scalability.
• Static code formatting: For simple syntax formatting, use dart format.

Process

flowchart TD
    A[Performance Issue Reported] --> B[Run Profile Mode: flutter run --profile]
    B --> C[Capture Timeline in DevTools]
    C --> D{Diagnose Thread Bottleneck}
    D -->|UI Thread > 16ms| E[Optimize Build/Layout Scope & Compute Offload]
    D -->|Raster Thread > 16ms| F[Reduce Overdraw, Clips & saveLayer Calls]
    D -->|First-run Stutter| G[Shader Warmup / Impeller Engine Migration]
    E --> H[Verify Frame Metrics Before vs. After]
    F --> H
    G --> H

1. Measure in Profile Mode (Never Guess)

Never attempt performance profiling in Debug mode (unoptimized JIT engine) or Release mode (stripped of DevTools hooks). Run in Profile mode:

flutter run --profile
flutter run --profile --trace-startup --verbose