Flutter Expert

---
name: Flutter Expert
description: Use when building cross-platform mobile and desktop applications with Flutter 3+, Dart, state management, and platform channels.
category: Languages
version: 1.0.0
tools: []
---

# Flutter 3+ Cross-Platform Development

Build cross-platform mobile and desktop applications using Flutter 3+ and Dart.

## Core Principles

- **Widgets are configuration.** Keep `build` methods declarative. Move logic to state management layers.
- **Composition over inheritance.** Build complex UIs by combining small, focused widgets.
- **Const constructors everywhere.** Mark widgets `const` to enable widget identity optimization and avoid rebuilds.
- **Test on real devices.** Emulators miss performance, platform-specific rendering, and gesture nuances.

## Widget Architecture

- Split widgets when `build` exceeds 80 lines. Extract into separate classes, not helper methods.
- `StatelessWidget` unless the widget owns mutable state (most widgets should be stateless).
- `StatefulWidget` only for local ephemeral state: animation controllers, text editing, scroll positions.
- Implement `Key` on list items and dynamically reordered widgets to preserve state across rebuilds.

## State Management

- **Riverpod 2.0** for dependency injection and reactive state. Prefer `ref.watch` over `ref.read` in `build` methods.
- `StateNotifier` or `AsyncNotifier` for complex state with business logic.
- `FutureProvider` and `StreamProvider` for async data mapping to single sources.
- Bloc/Cubit when requiring strict event/state separation with explicit transitions.
- Never store UI state (scroll position, tab index) in global state management.

## Navigation

- **GoRouter** for declarative, URL-based routing with deep link support.
- Define routes as constants: `static const String home = "/"`, `static const String profile = "/profile/:id"`.
- `ShellRoute` for persistent bottom navigation bars and tab layouts.
- Handle platform-specific back navigation: Android back button, iOS swipe-to-go-back, web history.

## Platform Integration

- `MethodChannel` for one-off platform calls (camera, biometrics, platform settings).
- `EventChannel` for continuous platform data streams (sensors, location, Bluetooth).
- **Pigeon** for type-safe platform channel code generation.
- `dart:ffi` and `ffigen` for direct C library bindings (performance-critical).

## Performance

- Use Flutter DevTools Performance overlay to identify janky frames (>16ms build or render).
- `ListView.builder` and `GridView.builder` for long scrollable lists. Never `ListView` with dynamic `children`.
- `RepaintBoundary` to isolate frequently updating widgets from static content.
- `Isolate.run` for CPU-intensive work: JSON parsing, image processing, cryptographic operations.
- Cache network images with `cached_network_image`. Resize to display size before rendering.

## Testing

- `testWidgets` and `WidgetTester` for widget interaction testing.
- `mockito` with `@GenerateMocks` for service layer mocking.
- `golden_toolkit` for screenshot-based regression testing.
- `integration_test` package for full-app flow testing on real devices.