Flutter Best Practices

Flutter clean architecture skill using Riverpod 3.x (codegen), Freezed 3.x (sealed classes), and GoRouter.

Core Stack

Architecture

Four layers. Dependencies flow inward: Presentation → Repository → Domain → Data.

lib/
├── core/           # Shared: theme, utils, widgets, navigation, services
├── features/       # Feature modules (auth, products, home, ...)
│   └── feature_x/
│       ├── data/           # Models, datasources (API/local)
│       ├── domain/         # Entities (pure Dart, no dependencies)
│       ├── repositories/   # Orchestrate data sources, map models → entities
│       └── presentation/   # Notifiers, screens, widgets
└── main.dart

Each layer has one job. Domain holds pure Dart entities. Data holds models (with toEntity()) and datasources. Repositories bridge them — mapping models→entities. Presentation manages state and UI. Always create separate data models and domain entities even for simple features; repositories call model.toEntity() to convert.

Critical Rules

1. Codegen only — Use @riverpod / @Riverpod(keepAlive: true). Legacy providers (StateProvider, etc.) are deprecated and lack codegen benefits.
2. Sealed classes — All Freezed classes use sealed class, not abstract class. Dart's sealed enables exhaustive switch — the compiler catches missing cases.
3. No prop drilling — Child widgets watch providers directly. Passing state through constructors couples parent-child and bypasses select() optimization.
4. Guard async — Check if (!ref.mounted) return; after every await in notifiers. The notifier may be disposed while the future is in flight.
5. Single Ref — Riverpod 3.0 unified all Ref types. AutoDisposeRef, FutureProviderRef, ExampleRef no longer exist.
6. Equality filtering — Providers use == to skip redundant notifications. Override updateShouldNotify only when default equality is insufficient.
7. Select in leaves — Use ref.watch(provider.select((s) => s.field)) in leaf widgets. Watching full state rebuilds the widget on every field change.
8. One file per class — Each entity, model, notifier, screen, and widget gets its own file. Avoids circular imports and keeps codegen output manageable.

Provider Decision Tree

Is it a repository, datasource, or service?
  → @Riverpod(keepAlive: true) — lives forever

Is it a feature notifier (manages mutable state)?
  → @Riverpod(keepAlive: true) class FeatureNotifier extends _$FeatureNotifier

Is it a computed value or one-time fetch?
  → @riverpod (auto-disposes when unused)

Does it need parameters?
  → Add parameters to the generated function (family via codegen)

Freezed Patterns

// Simple data class
@freezed
sealed class Product with _$Product {
  const Product._();  // Required for adding methods/getters

  const factory Product({
    required String id,
    required String name,
    @Default(0) int quantity,
  }) = _Product;

  factory Product.fromJson(Map<String, dynamic> json) => _$ProductFromJson(json);

  // Rich domain methods — derive from own fields
  bool get inStock => quantity > 0;
}

// Union type (exhaustive pattern matching)
@freezed
sealed class AuthState with _$AuthState {
  const factory AuthState.authenticated(User user) = Authenticated;
  const factory AuthState.unauthenticated() = Unauthenticated;
  const factory AuthState.loading() = AuthLoading;
}

Notifier Pattern

@Riverpod(keepAlive: true)
class ProductNotifier extends _$ProductNotifier {
  @override
  ProductState build() {
    _load();
    return const ProductState();
  }

  Future<void> _load() async {
    state = state.copyWith(isLoading: true);
    try {
      final items = await ref.read(productRepositoryProvider).fetchAll();
      if (!ref.mounted) return;
      state = state.copyWith(items: items, isLoading: false);
    } catch (e) {
      if (!ref.mounted) return;
      state = state.copyWith(isLoading: false, error: e.toString());
    }
  }
}

Code Generation

# Watch mode (recommended during development)
dart run build_runner watch -d

# One-time build
dart run build_runner build -d

# Clean build (resolve conflicts)
dart run build_runner clean && dart run build_runner build -d

Anti-Patterns

Router, sync, and utility anti-patterns are in their reference files: common-patterns.md (GoRouter redirect, delta sync) | extensions-utilities.md (context extensions, SnackBarUtils)

Reference Files

Consult the relevant reference when working on that topic. Each file has a Contents line at the top.