flutter-idioms

Flutter Idioms and Patterns (Riverpod 3)

Core Philosophy

Flutter is a UI toolkit first — performance is a first-class concern. const widgets and immutable data keep the render tree efficient. Riverpod 3 is the canonical state management solution: compile-safe, testable without BuildContext, no implicit global state, and with automatic retry and pause/resume built in.

Code generation is mandatory. All providers must use @riverpod / @Riverpod(keepAlive: true) annotations with riverpod_generator and build_runner. This catches type errors, missing overrides, and broken provider graphs at compile time — bugs are caught before they reach users.

Required dependencies:

# pubspec.yaml
dependencies:
  flutter_riverpod: 3.2.1
  riverpod_annotation: 4.0.2

dev_dependencies:
  riverpod_generator: 4.0.3
  build_runner: # latest
  riverpod_lint: # latest

Scope: This file covers Flutter/Dart coding idioms. For file and folder layout, see references/project-structure.md. For test naming, see testing-strategy.md. For general error handling principles, see error-handling-principles.md.

---

const Constructors — Everywhere

Make every widget const when possible. const widgets are created once and never rebuilt unless their inputs change — this is Flutter's most impactful performance optimization.

// ✅ const constructor — widget is rebuild-safe
class TaskCard extends StatelessWidget {
    const TaskCard({super.key, required this.task});
    final Task task;
    // ...
}

// Usage — compile-time constant
const TaskCard(task: myTask)

// ❌ Missing const — rebuilt on every parent rebuild
TaskCard(task: myTask)

Rules:

• Every StatelessWidget that has no mutable state must have a const constructor
• Pass const keyword at the call site, not just the definition
• Lint rule prefer_const_constructors must be enabled in analysis_options.yaml

---

Widget Decomposition

Large build methods are the primary source of performance problems and unmaintainable UI code.