flutter-performance

name	flutter-performance
description	Optimize the performance of your Flutter app
metadata	{"model":"models/gemini-3.1-pro-preview","last_modified":"Wed, 04 Mar 2026 21:54:56 GMT"}

Flutter Performance Optimization

Goal

Analyzes and optimizes Flutter application performance by identifying jank, excessive rebuilds, and expensive rendering operations. Implements best practices for UI rendering, state management, and layout constraints. Utilizes Flutter DevTools, Chrome DevTools (for web), and integration tests to generate actionable performance metrics, ensuring frames render within the strict 16ms budget.

Decision Logic

Evaluate the target application using the following decision tree to determine the optimization path:

1. Is the goal to establish a performance baseline?
   • Yes: Implement an integration test using traceAction and TimelineSummary.
   • No: Proceed to step 2.
2. Is the application running on Web?
   • Yes: Enable debugProfileBuildsEnabled and use Chrome DevTools Performance panel.
   • No: Run the app on a physical device in --profile mode and launch Flutter DevTools.
3. Which thread is showing jank (red bars > 16ms) in the DevTools Performance View?
   • UI Thread: Optimize build() methods, localize setState(), use const constructors, and replace string concatenation with StringBuffer.
   • Raster (GPU) Thread: Minimize saveLayer(), Opacity, Clip, and ImageFilter usage. Pre-cache complex images using RepaintBoundary.
   • Both: Start by optimizing the UI thread (Dart VM), as expensive Dart code often cascades into expensive rendering.

Instructions

1. Establish a Performance Baseline To measure performance programmatically, create an integration test that records a performance timeline. STOP AND ASK THE USER: "Do you want to run a baseline integration test to capture timeline metrics before optimizing?" If yes, implement the following exact driver and test implementation:

   test_driver/perf_driver.dart (Immutable operation):

   import 'package:flutter_driver/flutter_driver.dart' as driver;
   import 'package:integration_test/integration_test_driver.dart';
   
   Future<void> main() {
     return integrationDriver(
       responseDataCallback: (data) async {
         if (data != null) {
           final timeline = driver.Timeline.fromJson(
             data['scrolling_timeline'] as Map<String, dynamic>,
           );
           final summary = driver.TimelineSummary.summarize(timeline);
           await summary.writeTimelineToFile(
             'scrolling_timeline',
             pretty: true,
             includeSummary: true,
           );
         }
       },
     );
   }
   

   integration_test/scrolling_test.dart:

   import 'package:flutter/material.dart';
   import 'package:flutter_test/flutter_test.dart';
   import 'package:integration_test/integration_test.dart';
   import 'package:your_package/main.dart';
   
   void main() {
     final binding = IntegrationTestWidgetsFlutterBinding.ensureInitialized();
   
     testWidgets('Performance profiling test', (tester) async {
       await tester.pumpWidget(const MyApp());
       final listFinder = find.byType(Scrollable);
       final itemFinder = find.byKey(const ValueKey('target_item'));
   
       await binding.traceAction(() async {
         await tester.scrollUntilVisible(
           itemFinder,
           500.0,
           scrollable: listFinder,
         );
       }, reportKey: 'scrolling_timeline');
     });
   }
   

   Run the test using: flutter drive --driver=test_driver/perf_driver.dart --target=integration_test/scrolling_test.dart --profile --no-dds

2. Optimize UI Thread (Build Costs) If the UI thread exceeds 8ms per frame, refactor the widget tree:

   • Localize State: Move setState calls as low in the widget tree as possible.
   • Use const: Apply const constructors to short-circuit rebuild traversals.
   • String Building: Replace + operators in loops with StringBuffer.

   // BAD: Rebuilds entire widget tree
   setState(() { _counter++; });
   
   // GOOD: Encapsulated state
   class CounterWidget extends StatefulWidget { ... }
   // Inside CounterWidget:
   setState(() { _counter++; });
   

Constraints

• NEVER profile performance in Debug mode. Always use --profile mode on a physical device.
• NEVER override operator == on Widget objects. It results in O(N²) behavior and degrades performance. Rely on const caching instead.
• NEVER put a subtree in an AnimatedBuilder that does not depend on the animation. Build the static part once and pass it as the child parameter.
• DO NOT use constructors with a concrete List of children (e.g., Column, ListView) if most children are off-screen. Always use .builder constructors for lazy loading.
• DO NOT use saveLayer() unless absolutely necessary (e.g., dynamic overlapping shapes with transparency). Precalculate and cache static overlapping shapes.