evanca/flutter-ai-rules / skills/flutter-best-practices
flutter-best-practices
VerifiedUse when writing, reviewing, refactoring, or planning Flutter/Dart code — screens, features, project structure, state management, folders, widgets, cubits/blocs, repositories, services, or tests.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
| references/architecture-layers.md | markdown | 5.6 KB |
| references/dart-coding-practices.md | markdown | 5.5 KB |
| references/enterprise-scale.md | markdown | 6.2 KB |
| references/feature-structure.md | markdown | 6.5 KB |
| references/localization-package-boundaries.md | markdown | 3.0 KB |
references/feature-structure.md
View on GitHub# Feature-Based Structure
Based on LeanCode's feature-based Flutter architecture
(https://leancode.co/blog/feature-based-flutter-architecture), proven across
40+ projects from small apps to enterprise scale.
## The principle
Group code by **what it does for the user**, not by what kind of class it is.
A developer implements a user story ("let users see their loan documents"),
which cuts through every technical layer — UI, state, data. So everything
related to one feature lives under one directory:
```
lib/
└── features/
└── comment_section/
├── bloc/
│ └── comment_section_cubit.dart
├── comment_section.dart # feature entrypoint widget
└── widgets/
└── upvote_button.dart
```
Not this (layer-first — avoid):
```
lib/
├── blocs/ # every feature's cubits mixed together
├── widgets/ # every feature's widgets mixed together
└── models/
```
Why feature-first wins:
- developers work in parallel on different features without collisions
- all code for a feature is findable in one place, not scattered
- **feature-level innovation**: one feature's internal architecture can be
rewritten without touching any other feature
- scales from small projects to enterprise (at large scale, features graduate
into packages — see `enterprise-scale.md`)
## Anatomy of a feature
### 1. Entrypoint widget
The feature's public face: a `StatelessWidget` that takes all required
context via constructor and sets up the feature's dependencies (providers,
cubit creation) for its subtree.
```dart
class CommentSection extends StatelessWidget {
const CommentSection({super.key, required this.postId});
final Guid postId;
@override
Widget build(BuildContext context) {
return BlocProvider(
create: (context) => CommentSectionCubit(
client: context.read<ApiClient>(),
postId: postId,
)..fetch(),
child: const _CommentSectionView(),
);
}
}
```
Other features interact with this widget only — never with the feature's
internals.
### 2. State as a union type
Express the cubit's state as a sealed/union type so the UI must handle every
case. With `freezed`:
```dart
@freezed
class CommentSectionState with _$CommentSectionState {
const factory CommentSectionState.initial() = CommentSectionStateInitial;
const factory CommentSectionState.inProgress() = CommentSectionStateInProgress;
const factory CommentSectionState.failure({
required CommentSectionFailureReason reason,
}) = CommentSectionStateFailure;
const factory CommentSectionState.ready({
required List<Comment> comments,
}) = CommentSectionStateReady;
}
```
(Plain Dart 3 `sealed class` hierarchies work too; freezed adds
value-equality and copyWith for free.)
### 3. Cubit (state management)
The Cubit owns the data and every function that alters it. It guides UI
behavior purely through emitted states.
- **No `BuildContext` in a Cubit.** Ever. This keeps it detached from the
rendering pipeline and unit-testable in isolation.
- Dependencies (API client, repositories) come in through the constructor.
- Emit the union-type states; the widget maps state → UI.
```dart
class CommentSectionCubit extends Cubit<CommentSectionState> {
CommentSectionCubit({required this.client, required this.postId})
: super(const CommentSectionState.initial());
final ApiClient client;
final Guid postId;
Future<void> fetch() async {
emit(const CommentSectionState.inProgress());
try {
final response = await client.get(GetCommentSection(postId: postId));
emit(CommentSectionState.ready(comments: response.comments));
} catch (e, st) {
emit(const CommentSectionState.failure(
reason: CommentSectionFailureReason.network,
));
}
}
}
```
### 4. Presentation events (one-off effects)
Snackbars, dialogs, and navigation triggers are **not state** — they happen
once and shouldn't persist or replay on rebuild. Use
`package:bloc_presentation` to emit them as a separate event stream, and
listen in the widget (with `flutter_hooks` to avoid `StatefulWidget`
boilerplate for subscriptions).
Rule of thumb: if re-emitting the value on a rebuild would be wrong (showing
the snackbar twice), it's a presentation event, not state.
### 5. UI rendering
Map the state union exhaustively:
```dart
switch (state) {
CommentSectionStateInitial() ||
CommentSectionStateInProgress() => const _Loading(),
CommentSectionStateFailure(:final reason) => _Error(reason: reason),
CommentSectionStateReady(:final comments) => _CommentList(comments: comments),
}
```
## Dependency injection
Use `package:provider`, scoped to widget subtrees:
- a dependency's lifetime is tied to the widget tree — injected when the tree
mounts, disposed when it unmounts
- **global** dependencies (ApiClient, auth session) are provided at the app
root
- **feature-scoped** dependencies are provided in the feature entrypoint and
constructor-injected into the Cubit
Provider was chosen with eyes open: it lacks compile-time safety when
consuming dependencies, but the alternatives (e.g. riverpod) were judged to
introduce larger issues. Known limit: on very large apps, deeply nested trees
of global Providers can hit StackOverflowError (Flutter issue #85026) —
another reason to keep global providers few and push the rest into features.
## Data access
- Prefer a **backend-for-frontend** style: a dedicated, typed endpoint per
screen (`GetCommentSection(postId: ...)`) over generic REST endpoints that
over-fetch.
- It is fine for a Cubit to call the typed API client **directly**. Introduce
a repository as a *feature-level decision* when the feature actually needs
caching, offline mode, or merging sources — see `architecture-layers.md`
for what a repository owes you once you add it.
## Shared code between features
Shared components (design-system widgets, common utilities, shared domain
models) live outside `features/` — in `lib/common/` or dedicated packages —
and features depend on them, never on each other's internals. If feature A
needs something from feature B, either promote it to shared code or
communicate through events (see `enterprise-scale.md` for cross-domain
communication patterns).
## What this file deliberately doesn't decide
Feature structure is one slice of a real app. Navigation/deeplinks,
flavoring, monitoring, CI/CD, localization, design systems, golden/E2E tests,
and analytics all need their own decisions — several are covered in
`enterprise-scale.md`; the rest follow project conventions.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |