flutter-performance
/flutter-performance
Enforces Flutter runtime performance — const subtrees, minimal rebuild scope via ref.watch(select), lazy ListView/GridView builders and slivers, sized image decode (cacheWidth/ResizeImage), heavy work off the UI isolate via compute/Isolate, surgical RepaintBoundary, dispose everything, and measurement in profile mode on a floor device. Use when optimizing UI, diagnosing jank or dropped frames, tuning long lists or images, reviewing rebuild/repaint scope, or when the task mentions const, select, ListView.builder, cacheWidth, compute, RepaintBoundary, AnimatedBuilder, DevTools, raster thread, or
- Author
- zakariaf ↗
- Repository
- flutter-skills ↗
- Licence
- MIT
- Last repository change
- 23.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 7
No signals detected. Repository changed on 23.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Enforces Flutter runtime performance — const subtrees, minimal rebuild scope via ref.watch(select), lazy ListView/GridView builders and slivers, sized image decode (cacheWidth/ResizeImage), heavy work off the UI isolate via compute/Isolate, surgical RepaintBoundary, dispose everything, and measurement in profile mode on a floor device. Use when optimizing UI, diagnosing jank or dropped frames, tuning long lists or images, reviewing rebuild/repaint scope, or when the task mentions const, select, ListView.builder, cacheWidth, compute, RepaintBoundary, AnimatedBuilder, DevTools, raster thread, or
Original author description
Enforces Flutter runtime performance — const subtrees, minimal rebuild scope via ref.watch(select), lazy ListView/GridView builders and slivers, sized image decode (cacheWidth/ResizeImage), heavy work off the UI isolate via compute/Isolate, surgical RepaintBoundary, dispose everything, and measurement in profile mode on a floor device. Use when optimizing UI, diagnosing jank or dropped frames, tuning long lists or images, reviewing rebuild/repaint scope, or when the task mentions const, select, ListView.builder, cacheWidth, compute, RepaintBoundary, AnimatedBuilder, DevTools, raster thread, or
How it works
- Non-negotiable rules
- Narrow the rebuild scope
- Keep expensive children out of the animation loop
- Lazy lists and sized images
- Heavy work off the UI isolate
- Custom painting
- Profiling workflow
- Anti-patterns
- Definition of done
- Related skills
SKILL.md preview
---
name: flutter-performance
description: Enforces Flutter runtime performance — const subtrees, minimal rebuild scope via ref.watch(select), lazy ListView/GridView builders and slivers, sized image decode (cacheWidth/ResizeImage), heavy work off the UI isolate via compute/Isolate, surgical RepaintBoundary, dispose everything, and measurement in profile mode on a floor device. Use when optimizing UI, diagnosing jank or dropped frames, tuning long lists or images, reviewing rebuild/repaint scope, or when the task mentions const, select, ListView.builder, cacheWidth, compute, RepaintBoundary, AnimatedBuilder, DevTools, raster thread, or 60/120fps.
---
# Flutter Performance
Hold a steady 60 fps (<=16 ms/frame; <=8 ms on 120 Hz) on a floor device (low-end Android / older iPhone). Performance is a property you **measure in profile mode**, not one you assert. It comes from rebuilding less, painting cheaply, and keeping both the UI thread and the raster thread free.
## Non-negotiable rules
1. **`const` everything legal.** A `const` subtree is skipped on rebuild — the framework short-circuits it by identity. Keep `prefer_const_constructors` on as an error; a non-const literal that could be const is a lint failure, not a preference.
2. **Shrink the rebuild scope to the smallest changing widget.** Never `ref.watch(provider)` for a whole state object when one field changed — watch `provider.select((s) => s.field)`. A HUD counter tick must never rebuild a heavy sibling. Rebuild scope is the single biggest lever on build-thread cost.
3. **Lazy everything long.** `ListView.builder` / `GridView.builder` / slivers for variable or unbounded content. `ListView(children: items.map(...).toList())` builds every off-screen row up front — refuse it for anything not tiny and fixed.
4. **No expensive work in `build()`.** No `jsonDecode`, sort, regex, `DateTime` math, file/network, or large allocation — `build()` may run every frame. Compute in the Notifier/ViewModel once and cache the result in immutable state.
5. **Heavy CPU off the UI isolate.** Parse large payloads, process images, crunch numbers in `compute()` or a spawned `Isolate`. Blocking the UI thread is guaranteed jank; the raster thread cannot save you.
6. **Size image decode to the display slot.** `cacheWidth`/`cacheHeight` or `ResizeImage`, correct asset resolutions, `precacheImage` for above-the-fold art. Decoding a 4000 px source into a 100 px box spikes memory and OOMs cheap phones.
7. **Prefer the cheapest widget that does the job.** `ColoredBox`/`DecoratedBox` over `Container`, `SizedBox` for spacing, `FadeTransition`/`AnimatedOpacity` over the `Opacity` widget in hot paths. Avoid `ClipPath`/`saveLayer` inside scrolling lists — they force an offscreen buffer on the raster thread.
8. **`RepaintBoundary` around costly, independently-repainting subtrees** (an animation, a chart, a live indicator) so its repaint does not re-raster its neighbours. Do not sprinkle boundaries everywhere — each is a compositor layer that costs memory.
9. **Pass expensive children through `child:`.** `AnimatedBuilder`/`ValueListenableBuilder`/`StreamBuilder` rebuild only the `builder`; hand the unchanging subtree in via `child:` so it is built once, not per frame.
10. **Dispose to avoid leaks.** `AnimationController`s, gesture recognizers, stream subscriptions, timers, `TextEditingController`s, caches — released in `dispose()` (widgets) or `ref.onDispose` (providers). `autoDispose` scoped session state so it does not survive the screen.
11. **Measure in PROFILE mode on a real floor device with DevTools.** Debug timings are meaningless (JIT, asserts). Watch the **raster thread** as well as the UI thread — `saveLayer`/blur/clip cost shows there, not in Dart. Never ship a frame-budget number that was asserted, not measured.
## Narrow the rebuild scope
Watch the single field that changes, not the whole state object:
```dart
// Rebuilds only when the count changes, not on every OrderState mutation.
class OrderBadge extends ConsumerWidget {
const OrderBadge({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final count = ref.watch(orderProvider.select((s) => s.items.length));
return Text('$count');
}
}
```
`.select` runs the selector every publish but rebuilds only when the selected value's `==` changes, so its input must be an immutable value with real equality. See `state-management-riverpod` for the watch/read/listen split and `family` + `autoDispose`.
## Keep expensive children out of the animation loop
```dart
// The card is built once; only the transform recomputes each tick.
AnimatedBuilder(
animation: _controller,
child: const ProductCard(),
builder: (_, child) =>
Transform.scale(scale: _controller.value, child: child),
);
```
## Lazy lists and sized images
```dart
// Lazy — only visible rows are built.
ListView.builder(
itemCount: items.length,
itemBuilder: (context, i) => ItemTile(item: items[i]),
);
// Decode to the slot, not the source resolution.
Image.asset('assets/hero.png', cacheWidth: 240);
```
## Heavy work off the UI isolate
```dart
// parseItems is a top-level or static function (isolate entry-point rules).
final items = await compute(parseItems, jsonString);
```
## Custom painting
For a `CustomPainter`, the discipline is zero-allocation `paint()`, a `shouldRepaint` that is one value comparison over an immutable scene value, and a `repaint:` `Listenable` (the `AnimationController`) instead of `setState` in a ticker. That treatment lives in `custom-canvas-and-gestures`; the one performance-critical rule to carry here: **never allocate `Paint`/`Path`/`Gradient` inside `paint()`** — hold them as painter fields and mutate cheap properties.
## Profiling workflow
1. `flutter run --profile` on a physical floor device.
2. DevTools -> Performance; record while reproducing the jank.
3. For each over-budget frame, check whether the time is in **Build**, **Layout**, or **Raster**.
- Build-heavy -> narrow rebuild scope with `.select`, add `const`, move work out of `build()`.
- Raster-heavy -> reduce `Opacity`/clips/`saveLayer`, add a `RepaintBoundary`, simplify shaders.
4. Use "Track widget rebuilds" to find widgets rebuilding too often.
5. Fix one bottleneck, re-measure. Never optimize without a before/after measurement.
## Anti-patterns
- **Judging performance in debug mode** — JIT and asserts make timings fiction. Profile mode, real device, always.
- **Premature optimization with no profile data** — adds complexity, hides nothing; measure first.
- **`setState()` high in the tree** rebuilding a whole screen for a tiny change — scope the state down.
- **`ref.watch(provider)` for a whole object in a leaf** when one field changed — use `.select`.
- **`ListView(children: [...].toList())` for long/unbounded content** — builds every off-screen row.
- **`jsonDecode`/sort/`DateTime` math/regex in `build()`** — it may run every frame; precompute in the ViewModel.
- **`Opacity` widget for fades in scrolling lists** — forces `saveLayer`; use `FadeTransition` or fade via color.
- **Decoding full-resolution images** into small widgets — memory spikes and OOM on cheap phones.
- **Parsing large payloads / heavy loops on the UI isolate** — frozen frames; use `compute`.
- **`RepaintBoundary` on everything** — layer-memory bloat; use it surgically around independently-repainting subtrees.
- **`AnimatedBuilder`/`StreamBuilder` rebuilding an expensive child** instead of passing it via `child:`.
- **Rebuilding on every keystroke without debounce**, or unbounded caches/listeners that leak.
- **Allocating `Paint`/`Path` inside `paint()`** — per-frame garbage; hold them as fields.
## Definition of done
- [ ] `const` applied everywhere legal; `prefer_const_constructors` clean.
- [ ] Rebuilds scoped with `.select`; a tick in one widget never rebuilds a heavy sibling.
- [ ] Long/variable lists are lazy (`.builder`/slivers).
- [ ] No I/O, parsing, or heavy compute in `build()`; big work runs via `compute`/`Isolate`.
- [ ] Images sized to display (`cacheWidth`/`ResizeImage`); above-the-fold precached.
- [ ] Cheapest suitable widgets/effects chosen; `RepaintBoundary` used surgically; expensive children passed via `child:`.
- [ ] Any `CustomPainter` allocates nothing in `paint()`; `shouldRepaint` is one value compare.
- [ ] Controllers, recognizers, subscriptions, timers disposed; scoped session state `autoDispose`d; no leaks.
- [ ] Measured in profile mode on a floor device via DevTools — UI **and** raster threads under budget; no frames over 16 ms; claim backed by a recording.
## Related skills
- `state-management-riverpod` — the watch/read/listen split, `.select`, `family` + `autoDispose`, immutable state that makes `.select` correct.
- `widget-composition` — small `const` Widget classes over `_buildX` methods, dispose discipline, cheapest-widget choices.
- `custom-canvas-and-gestures` — zero-allocation `paint()`, `shouldRepaint` as one value compare, `repaint:` `Listenable`.
- `testing-strategy` — clock-injected pure core so heavy compute is testable off the UI isolate.
## References
- [Flutter — Performance best practices](https://docs.flutter.dev/perf/best-practices)
- [Flutter — Performance profiling / UI performance](https://docs.flutter.dev/perf/ui-performance)
- [Flutter — Concurrency and isolates / compute](https://docs.flutter.dev/perf/isolates)
- [Flutter — Impeller rendering engine](https://docs.flutter.dev/perf/impeller)
- [Flutter API — RepaintBoundary](https://api.flutter.dev/flutter/widgets/RepaintBoundary-class.html)
- [Flutter API — ResizeImage / cacheWidth](https://api.flutter.dev/flutter/painting/ResizeImage-class.html)
- [Riverpod — using select to filter rebuilds](https://riverpod.dev/docs/concepts/reading#using-select-to-filter-rebuilds)
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · zakariaf/flutter-skills | 100 | MIT |
| thienqo/flutter-skills | 100 | BSD-3-Clause |
| HoangNguyen0403/agent-skills-standard | 100 | MIT |
| evolplus/talos | 100 | Apache-2.0 |
| thiennc-tesoglobal/flutter-skills | 100 | BSD-3-Clause |
| Albaylar/Mobile-Development-Kit | 90 | MIT |
| Dee9975/cc-skills-flutter | 90 | MIT |
Database snapshot: 13.11.2026 · package version b03f12b99160 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100performance
Flutter performance rules — const constructors, RepaintBoundary placement, builder constructors for lists, image cache sizing, and keeping work out of build methods. Use this whenever implementing a list or grid, loading images, writing animations, investigating jank or dropped… - 100flutter-review-checklist
Use when reviewing a Flutter/Dart pull request or auditing existing Flutter code for quality — rebuild scope, const correctness, key usage, dispose/leak safety, BuildContext across async gaps, list and image performance, RepaintBoundary, accessibility semantics, and golden… - 100flutter-performance-profiling
Use when a Flutter app janks, drops frames, is slow to start, or feels heavy — diagnose with DevTools timeline, profile mode, the raster vs UI thread split, shader jank, and startup tracing, then fix the specific cause. Goes beyond the official flutter-fix-layout-issues (which… - 95flutter-expertise
Use this skill when the user says 'Flutter', 'Flutter app', 'widget rebuild', 'Riverpod', 'BLoC', 'Provider', 'go_router', 'Flutter performance', 'jank', 'const widget', 'platform channel', 'Flutter testing', 'golden test', 'Flutter release build', 'flavors'. Builds and reviews… - 100flutter-runtime-debugging
Reproduce, inspect, diagnose, and fix Flutter failures in a running app using logs, debugger attachment, DevTools, framework diagnostics, and minimal experiments. Use for runtime exceptions, incorrect live state, hangs, lifecycle failures, or failures that require execution… - 90flutter-dev
Flutter cross-platform development guide covering widget patterns, Riverpod/Bloc state management, GoRouter navigation, performance optimization, and platform-specific implementations. Includes const optimization, responsive layouts, testing strategies, and DevTools profiling.…