Dart Flutter Patterns

1---2name: dart-flutter-patterns3description: Production-ready Dart and Flutter patterns covering null safety, immutable state, async composition, widget architecture, popular state management frameworks (BLoC, Riverpod, Provider), GoRouter navigation, Dio networking, Freezed code generation, and clean architecture.4origin: ECC5---6 7# Dart/Flutter Patterns8 9## When to Use10 11Use this skill when:12- Starting a new Flutter feature and need idiomatic patterns for state management, navigation, or data access13- Reviewing or writing Dart code and need guidance on null safety, sealed types, or async composition14- Setting up a new Flutter project and choosing between BLoC, Riverpod, or Provider15- Implementing secure HTTP clients, WebView integration, or local storage16- Writing tests for Flutter widgets, Cubits, or Riverpod providers17- Wiring up GoRouter with authentication guards18 19## How It Works20 21This skill provides copy-paste-ready Dart/Flutter code patterns organized by concern:221. **Null safety** — avoid `!`, prefer `?.`/`??`/pattern matching232. **Immutable state** — sealed classes, `freezed`, `copyWith`243. **Async composition** — concurrent `Future.wait`, safe `BuildContext` after `await`254. **Widget architecture** — extract to classes (not methods), `const` propagation, scoped rebuilds265. **State management** — BLoC/Cubit events, Riverpod notifiers and derived providers276. **Navigation** — GoRouter with reactive auth guards via `refreshListenable`287. **Networking** — Dio with interceptors, token refresh with one-time retry guard298. **Error handling** — global capture, `ErrorWidget.builder`, crashlytics wiring309. **Testing** — unit (BLoC test), widget (ProviderScope overrides), fakes over mocks31 32## Examples33 34```dart35// Sealed state — prevents impossible states36sealed class AsyncState<T> {}37final class Loading<T> extends AsyncState<T> {}38final class Success<T> extends AsyncState<T> { final T data; const Success(this.data); }39final class Failure<T> extends AsyncState<T> { final Object error; const Failure(this.error); }40 41// GoRouter with reactive auth redirect42final router = GoRouter(43  refreshListenable: GoRouterRefreshStream(authCubit.stream),44  redirect: (context, state) {45    final authed = context.read<AuthCubit>().state is AuthAuthenticated;46    if (!authed && !state.matchedLocation.startsWith('/login')) return '/login';47    return null;48  },49  routes: [...],50);51 52// Riverpod derived provider with safe firstWhereOrNull53@riverpod54double cartTotal(Ref ref) {55  final cart = ref.watch(cartNotifierProvider);56  final products = ref.watch(productsProvider).valueOrNull ?? [];57  return cart.fold(0.0, (total, item) {58    final product = products.firstWhereOrNull((p) => p.id == item.productId);59    return total + (product?.price ?? 0) * item.quantity;60  });61}62```63 64---65 66Practical, production-ready patterns for Dart and Flutter applications. Library-agnostic where possible, with explicit coverage of the most common ecosystem packages.67 68---69 70## 1. Null Safety Fundamentals71 72### Prefer Patterns Over Bang Operator73 74```dart75// BAD — crashes at runtime if null76final name = user!.name;77 78// GOOD — provide fallback79final name = user?.name ?? 'Unknown';80 81// GOOD — Dart 3 pattern matching (preferred for complex cases)82final display = switch (user) {83  User(:final name, :final email) => '$name <$email>',84  null => 'Guest',85};86 87// GOOD — guard early return88String getUserName(User? user) {89  if (user == null) return 'Unknown';90  return user.name; // promoted to non-null after check91}92```93 94### Avoid `late` Overuse95 96```dart97// BAD — defers null error to runtime98late String userId;99 100// GOOD — nullable with explicit initialization101String? userId;102 103// OK — use late only when initialization is guaranteed before first access104// (e.g., in initState() before any widget interaction)105late final AnimationController _controller;106 107@override108void initState() {109  super.initState();110  _controller = AnimationController(vsync: this, duration: const Duration(milliseconds: 300));111}112```113 114---115 116## 2. Immutable State117 118### Sealed Classes for State Hierarchies119 120```dart121sealed class UserState {}122 123final class UserInitial extends UserState {}124 125final class UserLoading extends UserState {}126 127final class UserLoaded extends UserState {128  const UserLoaded(this.user);129  final User user;130}131 132final class UserError extends UserState {133  const UserError(this.message);134  final String message;135}136 137// Exhaustive switch — compiler enforces all branches138Widget buildFrom(UserState state) => switch (state) {139  UserInitial() => const SizedBox.shrink(),140  UserLoading() => const CircularProgressIndicator(),141  UserLoaded(:final user) => UserCard(user: user),142  UserError(:final message) => ErrorText(message),143};144```145 146### Freezed for Boilerplate-Free Immutability147 148```dart149import 'package:freezed_annotation/freezed_annotation.dart';150 151part 'user.freezed.dart';152part 'user.g.dart';153 154@freezed155class User with _$User {156  const factory User({157    required String id,158    required String name,159    required String email,160    @Default(false) bool isAdmin,161  }) = _User;162 163  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);164}165 166// Usage167final user = User(id: '1', name: 'Alice', email: 'alice@example.com');168final updated = user.copyWith(name: 'Alice Smith'); // immutable update169final json = user.toJson();170final fromJson = User.fromJson(json);171```172 173---174 175## 3. Async Composition176 177### Structured Concurrency with Future.wait178 179```dart180Future<DashboardData> loadDashboard(UserRepository users, OrderRepository orders) async {181  // Run concurrently — don't await sequentially182  final (userList, orderList) = await (183    users.getAll(),184    orders.getRecent(),185  ).wait; // Dart 3 record destructuring + Future.wait extension186 187  return DashboardData(users: userList, orders: orderList);188}189```190 191### Stream Patterns192 193```dart194// Repository exposes reactive streams for live data195Stream<List<Item>> watchCartItems() => _db196    .watchTable('cart_items')197    .map((rows) => rows.map(Item.fromRow).toList());198 199// In widget layer — declarative, no manual subscription200StreamBuilder<List<Item>>(201  stream: cartRepository.watchCartItems(),202  builder: (context, snapshot) => switch (snapshot) {203    AsyncSnapshot(connectionState: ConnectionState.waiting) =>204        const CircularProgressIndicator(),205    AsyncSnapshot(:final error?) => ErrorWidget(error.toString()),206    AsyncSnapshot(:final data?) => CartList(items: data),207    _ => const SizedBox.shrink(),208  },209)210```211 212### BuildContext After Await213 214```dart215// CRITICAL — always check mounted after any await in StatefulWidget216Future<void> _handleSubmit() async {217  setState(() => _isLoading = true);218  try {219    await authService.login(_email, _password);220    if (!mounted) return; // ← guard before using context221    context.go('/home');222  } on AuthException catch (e) {223    if (!mounted) return;224    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(e.message)));225  } finally {226    if (mounted) setState(() => _isLoading = false);227  }228}229```230 231---232 233## 4. Widget Architecture234 235### Extract to Classes, Not Methods236 237```dart238// BAD — private method returning widget, prevents optimization239Widget _buildHeader() {240  return Container(241    padding: const EdgeInsets.all(16),242    child: Text(title, style: Theme.of(context).textTheme.headlineMedium),243  );244}245 246// GOOD — separate widget class, enables const, element reuse247class _PageHeader extends StatelessWidget {248  const _PageHeader(this.title);249  final String title;250 251  @override252  Widget build(BuildContext context) {253    return Container(254      padding: const EdgeInsets.all(16),255      child: Text(title, style: Theme.of(context).textTheme.headlineMedium),256    );257  }258}259```260 261### const Propagation262 263```dart264// BAD — new instances every rebuild265child: Padding(266  padding: EdgeInsets.all(16.0),       // not const267  child: Icon(Icons.home, size: 24.0), // not const268)269 270// GOOD — const stops rebuild propagation271child: const Padding(272  padding: EdgeInsets.all(16.0),273  child: Icon(Icons.home, size: 24.0),274)275```276 277### Scoped Rebuilds278 279```dart280// BAD — entire page rebuilds on every counter change281class CounterPage extends ConsumerWidget {282  @override283  Widget build(BuildContext context, WidgetRef ref) {284    final count = ref.watch(counterProvider); // rebuilds everything285    return Scaffold(286      body: Column(children: [287        const ExpensiveHeader(), // unnecessarily rebuilt288        Text('$count'),289        const ExpensiveFooter(), // unnecessarily rebuilt290      ]),291    );292  }293}294 295// GOOD — isolate the rebuilding part296class CounterPage extends StatelessWidget {297  const CounterPage({super.key});298 299  @override300  Widget build(BuildContext context) {301    return const Scaffold(302      body: Column(children: [303        ExpensiveHeader(),        // never rebuilt (const)304        _CounterDisplay(),        // only this rebuilds305        ExpensiveFooter(),        // never rebuilt (const)306      ]),307    );308  }309}310 311class _CounterDisplay extends ConsumerWidget {312  const _CounterDisplay();313 314  @override315  Widget build(BuildContext context, WidgetRef ref) {316    final count = ref.watch(counterProvider);317    return Text('$count');318  }319}320```321 322---323 324## 5. State Management: BLoC/Cubit325 326```dart327// Cubit — synchronous or simple async state328class AuthCubit extends Cubit<AuthState> {329  AuthCubit(this._authService) : super(const AuthState.initial());330  final AuthService _authService;331 332  Future<void> login(String email, String password) async {333    emit(const AuthState.loading());334    try {335      final user = await _authService.login(email, password);336      emit(AuthState.authenticated(user));337    } on AuthException catch (e) {338      emit(AuthState.error(e.message));339    }340  }341 342  void logout() {343    _authService.logout();344    emit(const AuthState.initial());345  }346}347 348// In widget349BlocBuilder<AuthCubit, AuthState>(350  builder: (context, state) => switch (state) {351    AuthInitial() => const LoginForm(),352    AuthLoading() => const CircularProgressIndicator(),353    AuthAuthenticated(:final user) => HomePage(user: user),354    AuthError(:final message) => ErrorView(message: message),355  },356)357```358 359---360 361## 6. State Management: Riverpod362 363```dart364// Auto-dispose async provider365@riverpod366Future<List<Product>> products(Ref ref) async {367  final repo = ref.watch(productRepositoryProvider);368  return repo.getAll();369}370 371// Notifier with complex mutations372@riverpod373class CartNotifier extends _$CartNotifier {374  @override375  List<CartItem> build() => [];376 377  void add(Product product) {378    final existing = state.where((i) => i.productId == product.id).firstOrNull;379    if (existing != null) {380      state = [381        for (final item in state)382          if (item.productId == product.id) item.copyWith(quantity: item.quantity + 1)383          else item,384      ];385    } else {386      state = [...state, CartItem(productId: product.id, quantity: 1)];387    }388  }389 390  void remove(String productId) =>391      state = state.where((i) => i.productId != productId).toList();392 393  void clear() => state = [];394}395 396// Derived provider (selector pattern)397@riverpod398int cartCount(Ref ref) => ref.watch(cartNotifierProvider).length;399 400@riverpod401double cartTotal(Ref ref) {402  final cart = ref.watch(cartNotifierProvider);403  final products = ref.watch(productsProvider).valueOrNull ?? [];404  return cart.fold(0.0, (total, item) {405    // firstWhereOrNull (from collection package) avoids StateError when product is missing406    final product = products.firstWhereOrNull((p) => p.id == item.productId);407    return total + (product?.price ?? 0) * item.quantity;408  });409}410```411 412---413 414## 7. Navigation with GoRouter415 416```dart417final router = GoRouter(418  initialLocation: '/',419  // refreshListenable re-evaluates redirect whenever auth state changes420  refreshListenable: GoRouterRefreshStream(authCubit.stream),421  redirect: (context, state) {422    final isLoggedIn = context.read<AuthCubit>().state is AuthAuthenticated;423    final isGoingToLogin = state.matchedLocation == '/login';424    if (!isLoggedIn && !isGoingToLogin) return '/login';425    if (isLoggedIn && isGoingToLogin) return '/';426    return null;427  },428  routes: [429    GoRoute(path: '/login', builder: (_, __) => const LoginPage()),430    ShellRoute(431      builder: (context, state, child) => AppShell(child: child),432      routes: [433        GoRoute(path: '/', builder: (_, __) => const HomePage()),434        GoRoute(435          path: '/products/:id',436          builder: (context, state) =>437              ProductDetailPage(id: state.pathParameters['id']!),438        ),439      ],440    ),441  ],442);443```444 445---446 447## 8. HTTP with Dio448 449```dart450final dio = Dio(BaseOptions(451  baseUrl: const String.fromEnvironment('API_URL'),452  connectTimeout: const Duration(seconds: 10),453  receiveTimeout: const Duration(seconds: 30),454  headers: {'Content-Type': 'application/json'},455));456 457// Add auth interceptor458dio.interceptors.add(InterceptorsWrapper(459  onRequest: (options, handler) async {460    final token = await secureStorage.read(key: 'auth_token');461    if (token != null) options.headers['Authorization'] = 'Bearer $token';462    handler.next(options);463  },464  onError: (error, handler) async {465    // Guard against infinite retry loops: only attempt refresh once per request466    final isRetry = error.requestOptions.extra['_isRetry'] == true;467    if (!isRetry && error.response?.statusCode == 401) {468      final refreshed = await attemptTokenRefresh();469      if (refreshed) {470        error.requestOptions.extra['_isRetry'] = true;471        return handler.resolve(await dio.fetch(error.requestOptions));472      }473    }474    handler.next(error);475  },476));477 478// Repository using Dio479class UserApiDataSource {480  const UserApiDataSource(this._dio);481  final Dio _dio;482 483  Future<User> getById(String id) async {484    final response = await _dio.get<Map<String, dynamic>>('/users/$id');485    return User.fromJson(response.data!);486  }487}488```489 490---491 492## 9. Error Handling Architecture493 494```dart495// Global error capture — set up in main()496void main() {497  FlutterError.onError = (details) {498    FlutterError.presentError(details);499    crashlytics.recordFlutterFatalError(details);500  };501 502  PlatformDispatcher.instance.onError = (error, stack) {503    crashlytics.recordError(error, stack, fatal: true);504    return true;505  };506 507  runApp(const App());508}509 510// Custom ErrorWidget for production511class App extends StatelessWidget {512  @override513  Widget build(BuildContext context) {514    ErrorWidget.builder = (details) => ProductionErrorWidget(details);515    return MaterialApp.router(routerConfig: router);516  }517}518```519 520---521 522## 10. Testing Quick Reference523 524```dart525// Unit test — use case526test('GetUserUseCase returns null for missing user', () async {527  final repo = FakeUserRepository();528  final useCase = GetUserUseCase(repo);529  expect(await useCase('missing-id'), isNull);530});531 532// BLoC test533blocTest<AuthCubit, AuthState>(534  'emits loading then error on failed login',535  build: () => AuthCubit(FakeAuthService(throwsOn: 'login')),536  act: (cubit) => cubit.login('user@test.com', 'wrong'),537  expect: () => [const AuthState.loading(), isA<AuthError>()],538);539 540// Widget test541testWidgets('CartBadge shows item count', (tester) async {542  await tester.pumpWidget(543    ProviderScope(544      overrides: [cartNotifierProvider.overrideWith(() => FakeCartNotifier(count: 3))],545      child: const MaterialApp(home: CartBadge()),546    ),547  );548  expect(find.text('3'), findsOneWidget);549});550```551 552---553 554## References555 556- [Effective Dart: Design](https://dart.dev/effective-dart/design)557- [Flutter Performance Best Practices](https://docs.flutter.dev/perf/best-practices)558- [Riverpod Documentation](https://riverpod.dev/)559- [BLoC Library](https://bloclibrary.dev/)560- [GoRouter](https://pub.dev/packages/go_router)561- [Freezed](https://pub.dev/packages/freezed)562- Skill: `flutter-dart-code-review` — comprehensive review checklist563- Rules: `rules/dart/` — coding style, patterns, security, testing, hooks