dart-flutter-patterns

name	dart-flutter-patterns
description	Dart and Flutter patterns for widgets, state management (BLoC, Riverpod, Provider), GoRouter, Dio, and Freezed. Use when building Flutter apps, structuring Dart code, or choosing state management approaches.
origin	MCC

Dart/Flutter Patterns

When to Use

• Starting a new Flutter feature and need idiomatic patterns for state management, navigation, or data access
• Reviewing or writing Dart code and need guidance on null safety, sealed types, or async composition
• Setting up a new Flutter project and choosing between BLoC, Riverpod, or Provider
• Implementing secure HTTP clients, WebView integration, or local storage
• Writing tests for Flutter widgets, Cubits, or Riverpod providers
• Wiring up GoRouter with authentication guards

How It Works

This skill provides copy-paste-ready Dart/Flutter code patterns organized by concern:

1. Null safety — avoid !, prefer ?./??/pattern matching
2. Immutable state — sealed classes, freezed, copyWith
3. Async composition — concurrent Future.wait, safe BuildContext after await
4. Widget architecture — extract to classes (not methods), const propagation, scoped rebuilds
5. State management — BLoC/Cubit events, Riverpod notifiers and derived providers
6. Navigation — GoRouter with reactive auth guards via refreshListenable
7. Networking — Dio with interceptors, token refresh with one-time retry guard
8. Error handling — global capture, ErrorWidget.builder, crashlytics wiring
9. Testing — unit (BLoC test), widget (ProviderScope overrides), fakes over mocks

---

1. Null Safety Fundamentals

Prefer Patterns Over Bang Operator

// BAD — crashes at runtime if null
final name = user!.name;

// GOOD — provide fallback
final name = user?.name ?? 'Unknown';

// GOOD — Dart 3 pattern matching
final display = switch (user) {
  User(:final name, :final email) => '$name <$email>',
  null => 'Guest',
};

// GOOD — guard early return
String getUserName(User? user) {
  if (user == null) return 'Unknown';
  return user.name; // promoted to non-null
}

Avoid late Overuse

Use late only when initialization is guaranteed before first access (e.g., initState()). Prefer nullable with explicit initialization otherwise.

---

2. Immutable State

Sealed Classes for State Hierarchies

sealed class UserState {}
final class UserInitial extends UserState {}
final class UserLoading extends UserState {}
final class UserLoaded extends UserState {
  const UserLoaded(this.user);
  final User user;
}
final class UserError extends UserState {
  const UserError(this.message);
  final String message;
}

// Exhaustive switch — compiler enforces all branches
Widget buildFrom(UserState state) => switch (state) {
  UserInitial() => const SizedBox.shrink(),
  UserLoading() => const CircularProgressIndicator(),
  UserLoaded(:final user) => UserCard(user: user),
  UserError(:final message) => ErrorText(message),
};

Freezed for Boilerplate-Free Immutability

@freezed
class User with _$User {
  const factory User({
    required String id,
    required String name,
    required String email,
    @Default(false) bool isAdmin,
  }) = _User;

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}

final updated = user.copyWith(name: 'Alice Smith'); // immutable update

---

3. Async Composition

Structured Concurrency

final (userList, orderList) = await (
  users.getAll(),
  orders.getRecent(),
).wait; // Dart 3 record destructuring + Future.wait

BuildContext After Await

// CRITICAL — always check mounted after any await in StatefulWidget
Future<void> _handleSubmit() async {
  setState(() => _isLoading = true);
  try {
    await authService.login(_email, _password);
    if (!mounted) return; // guard before using context
    context.go('/home');
  } on AuthException catch (e) {
    if (!mounted) return;
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(e.message)));
  } finally {
    if (mounted) setState(() => _isLoading = false);
  }
}

---

4. Widget Architecture

Extract to Classes, Not Methods

// BAD — private method, prevents const optimization
Widget _buildHeader() => Container(...);

// GOOD — separate widget class, enables const
class _PageHeader extends StatelessWidget {
  const _PageHeader(this.title);
  final String title;
  @override
  Widget build(BuildContext context) => Container(...);
}

const Propagation and Scoped Rebuilds

Use const constructors to stop rebuild propagation. Isolate reactive parts (e.g., ref.watch) into small dedicated widgets so expensive siblings are not rebuilt.

---

5. State Management: BLoC/Cubit

class AuthCubit extends Cubit<AuthState> {
  AuthCubit(this._authService) : super(const AuthState.initial());
  final AuthService _authService;

  Future<void> login(String email, String password) async {
    emit(const AuthState.loading());
    try {
      final user = await _authService.login(email, password);
      emit(AuthState.authenticated(user));
    } on AuthException catch (e) {
      emit(AuthState.error(e.message));
    }
  }
}

---

6. Error Handling Architecture

void main() {
  FlutterError.onError = (details) {
    FlutterError.presentError(details);
    crashlytics.recordFlutterFatalError(details);
  };
  PlatformDispatcher.instance.onError = (error, stack) {
    crashlytics.recordError(error, stack, fatal: true);
    return true;
  };
  runApp(const App());
}

---

7. Testing Quick Reference

// Unit test
test('GetUserUseCase returns null for missing user', () async {
  final repo = FakeUserRepository();
  final useCase = GetUserUseCase(repo);
  expect(await useCase('missing-id'), isNull);
});

// BLoC test
blocTest<AuthCubit, AuthState>(
  'emits loading then error on failed login',
  build: () => AuthCubit(FakeAuthService(throwsOn: 'login')),
  act: (cubit) => cubit.login('[e-mail]', 'wrong'),
  expect: () => [const AuthState.loading(), isA<AuthError>()],
);

// Widget test
testWidgets('CartBadge shows item count', (tester) async {
  await tester.pumpWidget(
    ProviderScope(
      overrides: [cartNotifierProvider.overrideWith(() => FakeCartNotifier(count: 3))],
      child: const MaterialApp(home: CartBadge()),
    ),
  );
  expect(find.text('3'), findsOneWidget);
});

Prefer fakes over mocks for cleaner test code.

Reference Files

• state-management-examples.md — Riverpod notifiers, derived providers, cart total pattern, Provider examples
• navigation-and-networking.md — GoRouter with auth guards, ShellRoute, Dio interceptors, token refresh, stream patterns, scoped rebuild examples

References

• Effective Dart: Design
• Flutter Performance Best Practices
• Riverpod Documentation
• BLoC Library
• GoRouter
• Freezed
• Skill: flutter-dart-code-review — comprehensive review checklist
• Rules: rules/dart/ — coding style, patterns, security, testing, hooks