Flutter Widget Conventions

flutterdartmobile

Conventions for building maintainable Flutter applications covering widget decomposition, state management, navigation, theming, and performance patterns for iOS and Android.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

# Flutter Widget Conventions ## Project Structure - Organize by feature: `lib/features/auth/`, `lib/features/profile/`, `lib/features/feed/`. - Each feature folder contains: `screens/`, `widgets/`, `controllers/` (or `blocs/`), `models/`, `services/`. - Shared code lives in `lib/core/`: `theme/`, `widgets/`, `utils/`, `constants/`, `extensions/`. - Entry point: `lib/main.dart`. App widget: `lib/app.dart`. Keep both minimal. ## Widget Design - Split large widgets into smaller focused widgets. A widget's `build()` method should return one logical component, not a 100-line tree. - Prefer `StatelessWidget` by default. Reach for `StatefulWidget` only when local ephemeral state is needed. - Extract widget subtrees into private widget classes or builder methods when they become complex. - Name widgets by their purpose: `UserAvatarWidget`, `OrderSummaryCard`, `PrimaryButton` — not `MyWidget`. - Use `const` constructors wherever possible. Mark widgets and their children `const` to skip unnecessary rebuilds. ## State Management - Use a consistent state management approach project-wide: Riverpod (preferred), Bloc, or Provider. - With Riverpod: one provider per domain concern. Use `AsyncNotifierProvider` for async state, `NotifierProvider` for sync. - Never put business logic in `build()` methods. Delegate to controllers, notifiers, or blocs. - Do not call `setState` from async callbacks without checking `mounted` first. - Local form state (text fields, checkboxes) may use `StatefulWidget`. Shared or persistent state must use providers. ## Navigation - Use `go_router` or `auto_route` for declarative navigation with deep linking support. - Define all routes in a central `AppRouter` class. Never use magic string paths. - Pass minimal data between routes — prefer passing IDs and loading data in the destination screen. - Use `Navigator.pushNamed` only if not using a declarative router; otherwise use `context.go('/')`. ## Theming - Define the app theme in `lib/core/theme/app_theme.dart`. Use `ThemeData` with `ColorScheme.fromSeed`. - Access theme values via `Theme.of(context)` or `context.colorScheme` / `context.textTheme` extensions. - Never hardcode colors or text styles inline — use theme tokens. - Support both light and dark themes from day one. Test both modes during development. ## Performance - Use `ListView.builder` or `GridView.builder` for lists — never `ListView(children: [...])` for dynamic content. - Wrap expensive widget subtrees in `RepaintBoundary` to isolate repaints. - Use `cached_network_image` for network images — never `Image.network` directly. - Avoid calling `context.watch` (or `ref.watch`) in a widget that does not rebuild on that value's change. - Profile with Flutter DevTools before optimizing — measure first. ## Dart Code Style - Use `late final` for fields initialized once after construction. Use `final` for all immutable fields. - Use named constructors for different initialization paths: `User.fromJson(Map<String, dynamic> json)`. - Use `copyWith` methods on all model classes for immutable updates. - Prefer `async`/`await` over `.then()` chains. Always handle errors with `try/catch` in async methods. - Use `typedef` for complex function type signatures: `typedef OnSubmit = void Function(String value)`. ## File Conventions - One widget class per file. File name matches widget name in `snake_case`: `UserAvatarWidget` → `user_avatar_widget.dart`. - Export widgets from feature barrel files: `features/auth/auth.dart` re-exports all public auth widgets. - Test files mirror source structure: `test/features/auth/login_screen_test.dart`. ## Anti-Patterns - Do not use `BuildContext` across async gaps without checking `mounted`. - Do not place `MediaQuery.of(context)` deep in the widget tree — read it at the screen level and pass values down. - Do not build complex widget trees inside `ListView.builder` item builders without caching keys. - Do not use `GlobalKey` unless required for specific use cases (form validation, scroll controllers). - Do not ignore lints from `flutter_lints` — fix them, do not suppress.

CLI

npx mindaxis apply flutter-rules --target cursor --scope project

Используется в паках

Не используется ни в одном паке

← Правила