/flutter-performance

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),
)