flutter-best-practices

Group everything a feature needs under one directory: its cubit or bloc, entrypoint widget, and sub-widgets. Avoid top-level blocs/, widgets/, or models/ buckets that scatter a feature across the tree. Other features interact only with the entrypoint widget, never internals.

Model state as a sealed or union type (initial, inProgress, failure, ready) so every case is handled exhaustively, using freezed or Dart 3 sealed classes. Keep Cubits free of BuildContext, inject dependencies through the constructor, and emit one-off effects like snackbars as presentation events via bloc_presentation.

Add a repository only when a feature needs caching, offline support, or merging multiple data sources; a Cubit calling a typed API client directly is fine otherwise. Add a use case only when logic merges multiple repositories, is genuinely complex, or is reused by several view models.

Keep localization in the host app using gen-l10n with .arb files, and pass strings into reusable packages through constructor parameters. Package-owned ARB bundles only make sense for genuinely published packages with stable, independently translated copy.

The leancode_lint package bundles rules like use_padding, use_colored_box, and prefix_widgets_returning_slivers that automate widget guidance. Set strict lints at project start, since retrofitting them onto a mature codebase is far more expensive.