flutter-performance

SKILL.md

Identifies and eliminates performance bottlenecks in Flutter apps through systematic profiling and targeted optimization.

Provides a decision tree to diagnose jank on UI thread, Raster (GPU) thread, or both, with specific fixes for each

Includes integration test templates using traceAction and TimelineSummary to establish performance baselines and measure frame budgets

Covers UI optimization (localizing state, const constructors, StringBuffer usage) and Raster optimization (replacing Opacity widgets, avoiding expensive clipping)

Addresses layout inefficiencies, framework breaking changes with LayoutBuilder/OverlayEntry, and web-specific profiling via Chrome DevTools

Enforces constraints: profile in --profile mode only, avoid operator overrides on Widgets, and use lazy builders for long lists

Flutter Performance Optimization

Goal

Analyzes and optimizes Flutter application performance by identifying jank, excessive rebuilds, and expensive rendering operations. Implements best practices for UI rendering, state management, and layout constraints. Utilizes Flutter DevTools, Chrome DevTools (for web), and integration tests to generate actionable performance metrics, ensuring frames render within the strict 16ms budget.

Decision Logic

Evaluate the target application using the following decision tree to determine the optimization path:

Is the goal to establish a performance baseline?

Yes: Implement an integration test using traceAction and TimelineSummary.

No: Proceed to step 2.

Is the application running on Web?

Yes: Enable debugProfileBuildsEnabled and use Chrome DevTools Performance panel.

No: Run the app on a physical device in --profile mode and launch Flutter DevTools.

Which thread is showing jank (red bars > 16ms) in the DevTools Performance View?

UI Thread: Optimize build() methods, localize setState(), use const constructors, and replace string concatenation with StringBuffer.

Raster (GPU) Thread: Minimize saveLayer(), Opacity, Clip, and ImageFilter usage. Pre-cache complex images using RepaintBoundary.

Both: Start by optimizing the UI thread (Dart VM), as expensive Dart code often cascades into expensive rendering.

Instructions