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).

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.

1. 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.

1. 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.

1. 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.

1. 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.

Coding

1. Prefer intent-revealing widgets over Container. Use Padding,

SizedBox, ColoredBox, DecoratedBox, Center — they are const-able
and self-describing. Container is fine only when combining several
properties at once.

1. Use modern Dart. Pattern matching (if (x case final v?)), switch

expressions with exhaustiveness, records and destructuring, collection
if/for/spreads instead of .add() loops, expression bodies for
pass-through async functions (no redundant async/await).

1. Prefix sliver-returning widgets with Sliver so misuse in the wrong

scroll context is caught at a glance.

1. Tests tell a story. Use expressive matchers (isEmpty, throwsA,

isA, completion) and minimize dependencies — plain Text/SizedBox
over design-system widgets in test fixtures. Test cubits/view models in
isolation from the widget tree.

1. Every // ignore: gets a reason on the same or preceding line. Log

errors with dedicated error/stackTrace parameters, never string
interpolation.

Workflow checklists

Adding a new feature/screen

1. Read references/feature-structure.md

and mirror the existing project's conventions for the feature directory.

1. Define the state as a union type first; then the cubit/view model; then

the widgets. Constructor-inject dependencies; scope them to the feature's
widget subtree.

1. Data comes in through a repository or typed API client — never fetched

inside a widget.

1. Add unit tests for the cubit/view model logic before wiring UI details.

Reviewing Flutter code

Check, in order of importance:

1. Logic in the right layer (rule 1–2)? Any BuildContext in business logic?
2. State modeled as immutable union types, all cases handled?
3. Feature self-contained, or does it reach into another feature's internals?
4. Widget choices (rule 6), modern Dart (rule 7), sliver naming (rule 8)?
5. Tests present for logic, readable, minimal dependencies?
6. Unexplained // ignore:, string-interpolated error logs, deprecated

patterns still spreading?

Starting a new project

1. Read references/architecture-layers.md

for the layer blueprint and
references/feature-structure.md for the
folder skeleton.

1. If more than ~2 teams or clearly separable domains are involved, read

references/enterprise-scale.md and
consider a Melos monorepo with one package per domain from day one.

1. Set up strict lints early (leancode_lint or equivalent + custom rules) —

retrofitting is far more expensive.

Package palette

Defaults that these standards assume (swap for project-local equivalents when
the codebase already uses something else):

• State: bloc (Cubit) + freezed for union-type states;

bloc_presentation for one-off UI events

• DI: provider scoped to widget subtrees (accepting its lack of

compile-time safety as the lesser evil)

• Boilerplate reduction: flutter_hooks
• Monorepo: melos
• Localization: flutter_localizations + intl with .arb files
• Lints: leancode_lint
• E2E/UI tests: patrol

The official Flutter guide is state-management-agnostic (MVVM with
ChangeNotifier works too); what matters is the layer separation, not the
package. See the reference files for rationale and trade-offs.