Flutter performance audit

Flutter Widget Rebuild & Performance Audit

Instructions

Use Flutter DevTools plus code review to find and fix the common causes of jank and wasted rebuilds.

1. Measure First

• Run in profile mode: flutter run --profile — debug mode is not representative.
• Open DevTools → Performance tab. Record a trace while reproducing the jank.
• Look for frames > 16ms (60Hz) or > 8ms (120Hz). Identify the dominant phase: UI thread (Dart) vs Raster thread (GPU).

2. Find Excessive Rebuilds

• DevTools → Performance → Track widget builds and Highlight repaints.
• Enable the Rebuild Stats panel. Any widget rebuilding more than expected is a candidate.
• In code, add debugPrint('build $runtimeType') in suspect build methods to count rebuilds in dev.

Common culprits:

• Missing const on leaf widgets → entire subtree rebuilds with parent.
• context.watch / ref.watch at the top of a screen → whole screen rebuilds on any state change.
• New Function / Controller / Decoration instances created inside build.
• Parent widget does not use ==/hashCode (not @immutable), causing child to think it changed.

3. Narrow Rebuild Scope

• Extract children into separate widgets so their build only runs when their own state changes.
• Read providers as deep as possible. Use Consumer / Selector / BlocSelector to subscribe to a slice of state.
• Use ValueListenableBuilder / AnimatedBuilder for tight animation updates instead of calling setState on the whole screen.

4. Lists and Grids

• Use ListView.builder / SliverList.builder — never ListView(children: [...]) for long lists.
• Set itemExtent or prototypeItem when row height is uniform — enables O(1) scrolling.
• Add stable ValueKey(item.id) to list items that can reorder.
• Use AutomaticKeepAliveClientMixin or PageStorageKey only when state preservation is actually needed.

5. Images

• Always set cacheWidth/cacheHeight (or memCacheWidth/memCacheHeight in cached_network_image).
• Reuse ImageProvider instances. See flutter-images skill.

6. Raster / GPU Issues

• Avoid full-screen BackdropFilter (blurs) — expensive on the raster thread.
• Avoid stacked Opacity / ClipRRect on animating children — prefer FadeTransition and pre-baked shapes.
• Enable the Raster Cache layer overlay (DevTools) to confirm static sublayers are cached.

7. Isolates for CPU Work

Parsing large JSON, image decoding, or cryptography on the UI thread causes jank. Offload to Isolate.run(...) (Dart 3) or compute(fn, arg).

8. Audit Checklist

• flutter analyze passes with prefer_const_constructors + prefer_const_literals enabled.
• No widget in the performance trace rebuilds more than expected.
• Lists use .builder, keys, and bounded item size.
• No Opacity, Clip*, or BackdropFilter on hot animated subtrees.
• JSON parsing > ~10ms is moved to an isolate.