Flutter Best Practices

Use this skill for Flutter apps built with a feature-first MVVM architecture, Riverpod 3.x code generation, Freezed 3.x sealed classes, and GoRouter.

Core Stack

Architecture

Use a feature-first MVVM structure. Organize code by feature first, then split each feature into data, domain, repositories, and presentation.

Treat presentation/ as the MVVM layer:

• Screens and widgets are the View.
• Riverpod notifiers are the ViewModel.
• domain/ holds pure business entities.
• data/ holds models and data sources.
• repositories/ orchestrate reads, writes, mapping, and caching for the feature.

lib/
|-- core/           # Shared code: theme, utils, widgets, navigation, services
|-- features/       # Feature modules (auth, products, home, ...)
|   `-- feature_x/
|       |-- data/           # Models and data sources (API/local)
|       |-- domain/         # Pure Dart entities with no framework dependencies
|       |-- repositories/   # Coordinate data sources and map models to entities
|       `-- presentation/   # Notifiers, screens, and widgets
`-- main.dart

Keep each layer focused on one responsibility. Domain defines entities. Data handles models and data sources. Repositories coordinate feature data flow. Presentation manages UI state and user interaction through MVVM-style notifiers.

Critical Rules

1. Use code generation only. Prefer @riverpod or @Riverpod(keepAlive: true). Do not use StateProvider, StateNotifierProvider, or ChangeNotifierProvider.
2. Use sealed classes with Freezed. Declare Freezed types as sealed class, not abstract class.
3. Avoid prop drilling. Let child widgets watch providers directly instead of receiving provider state through constructors.
4. Guard async work. After every await in a notifier, check if (!ref.mounted) return;.
5. Use a single Ref type. Riverpod 3.x uses Ref. Do not use AutoDisposeRef, FutureProviderRef, or generated ref subtypes.
6. Rely on equality filtering. Providers already use == to filter updates. Override updateShouldNotify only when necessary.
7. Use select in leaf widgets. Prefer ref.watch(provider.select((s) => s.field)) when a widget needs only one field.
8. Keep one class per file. Each entity, model, notifier, screen, and widget should live in its own file.
9. Stay feature-first. Do not move feature-specific code into app-wide type folders.
10. Keep MVVM boundaries clear. Put UI logic in widgets and Riverpod notifiers, not in repositories or datasources.

Provider Decision Tree

Is it a repository, datasource, or service?
  -> Use @Riverpod(keepAlive: true) so it stays alive

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

Is it a computed value or one-time fetch?
  -> Use @riverpod so it auto-disposes when unused

Does it need parameters?
  -> Add parameters to the generated function and let codegen create the family

Freezed Patterns

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

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

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

  // Keep domain behavior on the model itself.
  bool get inStock => quantity > 0;
}

// Union type with 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 to resolve conflicts
dart run build_runner clean && dart run build_runner build -d

Quick Imports

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';
import 'package:freezed_annotation/freezed_annotation.dart';
import 'package:go_router/go_router.dart';
import 'package:my_app/core/extensions/extensions.dart'; // Context, string, and date extensions

// In route files
part 'routes.g.dart';

Anti-Patterns

Reference Files

Read only the reference file that matches the task.