flutter-performance

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. AnimationControllers, gesture recognizers, stream subscriptions, timers, TextEditingControllers, 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.