.cursorrules (deprecated)

1# Flutter with Dart — Cursor Rules
2 
3You are an expert Flutter developer building cross-platform mobile and web applications with Dart, following Flutter best practices and Material Design 3.
4 
5## Code Style
6 
7- Use Dart 3+ features: records, patterns, sealed classes, class modifiers (`final`, `base`, `interface`).
8- Follow Effective Dart guidelines. Use `dart_style` (dartfmt) for formatting.
9- Use `lowerCamelCase` for variables, functions, and parameters. `UpperCamelCase` for classes, enums, typedefs, and extensions. `lowercase_with_underscores` for file names and libraries.
10- Prefer `final` over `var` for variables that don't change after initialization.
11- Use `const` constructors wherever possible — it improves widget rebuild performance.
12- Use type annotations for function parameters, return types, and public API. Let Dart infer types for local variables.
13- Use `///` doc comments on all public classes, methods, and properties. Start with a single-sentence summary.
14- Use trailing commas on all parameter lists and collection literals for consistent formatting.
15- Prefer `String interpolation $variable` over concatenation.
16- Run `dart analyze` with no issues before committing. Enable `strict-casts` and `strict-raw-types`.
17 
18## Widget Architecture
19 
20- Prefer composition over inheritance. Build complex UIs by combining small, focused widgets.
21- Keep the `build()` method concise. Extract sub-widgets into private methods or separate widget classes.
22- Use `StatelessWidget` by default. Only use `StatefulWidget` when the widget has mutable state.
23- Split large widgets into smaller widgets rather than using many helper methods. Separate widget classes optimize rebuild performance.
24- Use `const` constructors for widgets that don't depend on runtime data.
25- Never put business logic in widgets. Widgets are for UI only.
26- Use `Key` parameters when the widget tree can change (lists, conditional rendering).
27 
28## State Management
29 
30- Use Riverpod as the primary state management solution. Prefer Riverpod over Provider, BLoC, or GetX for new projects.
31- Define providers outside of widgets. Use `ref.watch()` in `build()` for reactive UI, `ref.read()` for one-time reads in callbacks.
32- Use `StateNotifierProvider` or `NotifierProvider` for complex state logic.
33- Use `FutureProvider` for async data fetching. Use `StreamProvider` for real-time data.
34- Keep state classes immutable. Use `copyWith()` for state updates.
35- Use `AsyncValue` pattern for loading/error/data states. Handle all three in the UI.
36- Scope providers to features. Create a `providers/` directory per feature module.
37 
38## Navigation
39 
40- Use GoRouter for declarative routing. Define routes in a central `router.dart` file.
41- Use typed route parameters. Define route path constants to avoid magic strings.
42- Use `context.go()` for navigation, `context.push()` for adding to the stack.
43- Use shell routes for persistent bottom navigation or side navigation.
44- Handle deep links by defining route patterns that match the expected URL structure.
45- Use redirect guards for authentication: redirect unauthenticated users to login.
46- Use `StatefulShellRoute` for tabs that preserve state across tab switches.
47 
48## Layout and Design
49 
50- Follow Material Design 3 guidelines. Use `MaterialApp` with `useMaterial3: true`.
51- Use `ThemeData` with `ColorScheme.fromSeed()` for consistent theming.
52- Use `LayoutBuilder` and `MediaQuery` for responsive layouts. Define breakpoints for mobile, tablet, desktop.
53- Use `Flex`, `Column`, `Row`, `Expanded`, `Flexible` for layout. Avoid hardcoded sizes.
54- Use `SizedBox` for spacing between widgets. Avoid `Padding` when `SizedBox` suffices.
55- Use `SafeArea` to avoid system UI overlap (notches, status bar, navigation bar).
56- Use `Scaffold` as the root of each screen with `AppBar`, `body`, `bottomNavigationBar`, and `floatingActionButton`.
57- Extract theme-specific values from `Theme.of(context)`. Never hardcode colors, font sizes, or spacing.
58 
59## Networking
60 
61- Use `dio` for HTTP networking with interceptors for auth, logging, and error handling.
62- Create a centralized API client class that configures base URL, headers, and interceptors.
63- Use data classes for API responses. Parse JSON into typed Dart objects.
64- Use `freezed` for immutable data classes with `fromJson`/`toJson` generated by `json_serializable`.
65- Handle network errors gracefully: timeout, no connection, server errors. Show user-friendly messages.
66- Use `CancelToken` to cancel requests when widgets are disposed.
67- Cache API responses with an appropriate strategy (stale-while-revalidate, cache-first).
68 
69## Error Handling
70 
71- Use `sealed class` for result types: `sealed class Result<T> { Success(T data); Failure(AppException error); }`.
72- Define domain-specific exception classes. Map API errors to domain exceptions in the repository layer.
73- Use `try/catch` with specific exception types. Never use bare `catch`.
74- Show user-friendly error messages with `SnackBar` or inline error widgets. Never show raw exception messages.
75- Use `ErrorWidget.builder` for custom error widgets during development.
76- Log errors with a logging framework. Include stack traces for unexpected errors.
77- Use `FlutterError.onError` to capture widget build errors.
78 
79## Testing
80 
81- Use `flutter_test` for widget tests, `test` for unit tests, `integration_test` for integration tests.
82- Write unit tests for business logic, state management, and data models.
83- Write widget tests for UI components. Use `find.byType`, `find.text`, `find.byKey` for element queries.
84- Use `tester.pumpWidget()` to render widgets, `tester.tap()` and `tester.enterText()` for interactions.
85- Mock dependencies with `mocktail` or `mockito`. Create fakes for complex dependencies.
86- Test all states: loading, data, error, empty.
87- Achieve high test coverage on business logic. Visual components need fewer tests.
88- Place tests in `test/` mirroring the `lib/` structure.
89 
90## File Structure
91 
92```
93lib/
94  main.dart              — Entry point, app setup
95  app.dart               — MaterialApp, router, theme configuration
96  core/
97    theme/
98      app_theme.dart     — ThemeData configuration
99      colors.dart        — Color constants
100    network/
101      api_client.dart    — Dio client setup
102      interceptors.dart  — Auth, logging interceptors
103    utils/
104      extensions.dart    — Dart extension methods
105      validators.dart    — Input validation
106    errors/
107      app_exception.dart — Exception classes
108      error_handler.dart — Global error handling
109  features/
110    auth/
111      data/
112        auth_repository.dart
113        models/user_model.dart
114      presentation/
115        screens/login_screen.dart
116        widgets/login_form.dart
117        providers/auth_provider.dart
118    home/
119      data/
120      presentation/
121        screens/home_screen.dart
122        widgets/
123        providers/
124  shared/
125    widgets/              — Reusable UI components
126      app_button.dart
127      loading_indicator.dart
128      error_view.dart
129    providers/            — App-wide providers
130  router/
131    app_router.dart      — GoRouter configuration
132    routes.dart          — Route constants
133test/
134  features/
135    auth/
136      auth_repository_test.dart
137      login_screen_test.dart
138integration_test/
139  app_test.dart
140```
141 
142## Performance
143 
144- Use `const` constructors aggressively. Every `const` widget avoids unnecessary rebuilds.
145- Use `ListView.builder` for long lists (not `ListView` with `children`). This builds items lazily.
146- Use `RepaintBoundary` to isolate frequently updated widgets from the rest of the tree.
147- Profile with Flutter DevTools. Check for jank, excessive rebuilds, and memory leaks.
148- Use `compute()` for expensive computations to run them on a separate isolate.
149- Optimize images: use appropriate resolution, cache network images with `cached_network_image`.
150- Minimize widget tree depth. Flatter trees rebuild faster.
151- Use `AutomaticKeepAliveClientMixin` for tab views that should preserve state.
152 
153## Security
154 
155- Store sensitive data (tokens, keys) with `flutter_secure_storage`. Never use SharedPreferences for secrets.
156- Use HTTPS for all network requests. Pin certificates in production if handling sensitive data.
157- Validate all user input on both client and server.
158- Obfuscate Dart code in release builds: `flutter build --obfuscate --split-debug-info`.
159- Never hardcode API keys or secrets in source code. Use `--dart-define` for build-time configuration.
160- Sanitize data before displaying user-generated content.
161