flutter-best-practices

Flutter Best Practices

Standards for building maintainable Flutter apps, distilled from the official Flutter architecture guide and LeanCode's experience shipping 40+ Flutter projects (including a 30-developer banking app). Apply these when writing new code; when touching existing code, prefer consistency with the surrounding codebase and raise conflicts with these standards rather than silently rewriting.

How to use this skill

Read the reference file that matches the task. Read more than one when tasks overlap (e.g. a new feature touches both structure and coding style).

Task	Read
Design layers, decide where logic lives, MVVM, repositories/services	references/architecture-layers.md
Create/organize a feature, folder structure, state management wiring	references/feature-structure.md
Write or review Dart/Flutter code, widgets, tests, lints	references/dart-coding-practices.md
Multi-team/multi-package apps, monorepo, navigation, localization, API contracts, E2E tests	references/enterprise-scale.md
App localization setup, reusable UI package string ownership, language picker visibility	references/localization-package-boundaries.md

For a quick task (small widget fix, one-line review comment), the core rules below may be enough on their own.

Core rules (always apply)

Architecture

1. Separate UI from data. Two broad layers: UI (views + view models / cubits) and Data (repositories + services). Dependencies point one way: View → ViewModel → Repository → Service. Lower layers never import upper layers. Repositories never depend on each other.
2. Views hold no business logic. Widgets may contain show/hide conditionals, animation, layout, and simple routing logic — nothing that transforms or decides about data. All data logic lives in the view model (or cubit/bloc), which has no access to BuildContext.
3. Organize by feature, not by layer. Everything a feature needs — state management, widgets, models — lives under one feature directory. Don't create top-level blocs/, widgets/, models/ buckets that scatter a feature across the tree.
4. State is immutable and explicit. Model UI state as a sealed/union type (initial / inProgress / failure / ready) so every case is handled exhaustively. One-off effects (snackbars, navigation) are events, not state.
5. Add layers only when they pay for themselves. Start with view-model → API client. Introduce a repository when you need caching, offline, or merging sources. Introduce a use case only when logic merges multiple repositories, is genuinely complex, or is reused by several view models.