Skip to content
Skills Library
Programming · Review & audit

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

Licence
MIT
Last repository change
23.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
7
Deprecation

No signals detected. Repository changed on 23.09.2026, without references to retired models or APIs.

Licence

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

  1. Non-negotiable rules
  2. Narrow the rebuild scope
  3. Keep expensive children out of the animation loop
  4. Lazy lists and sized images
  5. Heavy work off the UI isolate
  6. Custom painting
  7. Profiling workflow
  8. Anti-patterns
  9. Definition of done
  10. Related skills
Original SKILL.md headings · 129 lines, 1,227 words
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

RepositoryScoreLicence
This page · zakariaf/flutter-skills100MIT
thienqo/flutter-skills100BSD-3-Clause
HoangNguyen0403/agent-skills-standard100MIT
evolplus/talos100Apache-2.0
thiennc-tesoglobal/flutter-skills100BSD-3-Clause
Albaylar/Mobile-Development-Kit90MIT
Dee9975/cc-skills-flutter90MIT

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.…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.