---

name: flutter-performance description: Optimize Flutter widget rebuilds, memory usage, rendering, and scrolling performance. Use when diagnosing jank, reducing rebuilds, or improving list performance—not performance tests, monitoring setup, or API optimization. metadata: triggers: files: - 'lib/presentation/**' - 'pubspec.yaml' - 'ListView.builder' keywords: - const - buildWhen - Isolate - RepaintBoundary

Performance

Priority: P1 (HIGH)

• Rebuilds: Use const widgets and buildWhen / select for granular updates.
• Lists: Always use ListView.builder for item recycling.
• Heavy Tasks: Use compute() or Isolates for parsing/logic.
• Repaints: Use RepaintBoundary for complex animations. Use debugRepaintRainbowEnabled to debug.
• Images: Use CachedNetworkImage + memCacheWidth. precachePicture for SVGs.
• Keys: Provide ValueKey for list items and stable IDs for reconciliation.
• Resource Cleanup: Dispose controllers/streams in dispose().
• Pagination: Default to 20 items per page for network lists.
• Build Purity: Keep build methods free of heavy work; move logic to BLoC/Application.
• Image Resizing: Always set maxWidth/maxHeight when loading images.

Anti-Patterns

• No Root setState(): Use BlocBuilder with buildWhen or context.select() for granular updates
• No Heavy Business in build(): Move sorting/filtering/heavy logic to BLoC or compute()
• No Non-const Leaf Nodes: Apply const to all static widgets to skip unnecessary reconciliation
• No Large Column Lists: Use ListView.builder for efficient item recycling in large lists

BlocBuilder<UserBloc, UserState>(
  buildWhen: (p, c) => p.id != c.id,
  builder: (context, state) => Text(state.name),
)