Cursor rule

1---
2paths:
3  - "**/*.dart"
4  - "**/pubspec.yaml"
5  - "**/analysis_options.yaml"
6---
7# Dart/Flutter Coding Style
8 
9> This file extends [common/coding-style.md](../common/coding-style.md) with Dart and Flutter-specific content.
10 
11## Formatting
12 
13- **dart format** for all `.dart` files — enforced in CI (`dart format --set-exit-if-changed .`)
14- Line length: 80 characters (dart format default)
15- Trailing commas on multi-line argument/parameter lists to improve diffs and formatting
16 
17## Immutability
18 
19- Prefer `final` for local variables and `const` for compile-time constants
20- Use `const` constructors wherever all fields are `final`
21- Return unmodifiable collections from public APIs (`List.unmodifiable`, `Map.unmodifiable`)
22- Use `copyWith()` for state mutations in immutable state classes
23 
24```dart
25// BAD
26var count = 0;
27List<String> items = ['a', 'b'];
28 
29// GOOD
30final count = 0;
31const items = ['a', 'b'];
32```
33 
34## Naming
35 
36Follow Dart conventions:
37- `camelCase` for variables, parameters, and named constructors
38- `PascalCase` for classes, enums, typedefs, and extensions
39- `snake_case` for file names and library names
40- `SCREAMING_SNAKE_CASE` for constants declared with `const` at top level
41- Prefix private members with `_`
42- Extension names describe the type they extend: `StringExtensions`, not `MyHelpers`
43 
44## Null Safety
45 
46- Avoid `!` (bang operator) — prefer `?.`, `??`, `if (x != null)`, or Dart 3 pattern matching; reserve `!` only where a null value is a programming error and crashing is the right behaviour
47- Avoid `late` unless initialization is guaranteed before first use (prefer nullable or constructor init)
48- Use `required` for constructor parameters that must always be provided
49 
50```dart
51// BAD — crashes at runtime if user is null
52final name = user!.name;
53 
54// GOOD — null-aware operators
55final name = user?.name ?? 'Unknown';
56 
57// GOOD — Dart 3 pattern matching (exhaustive, compiler-checked)
58final name = switch (user) {
59  User(:final name) => name,
60  null => 'Unknown',
61};
62 
63// GOOD — early-return null guard
64String getUserName(User? user) {
65  if (user == null) return 'Unknown';
66  return user.name; // promoted to non-null after the guard
67}
68```
69 
70## Sealed Types and Pattern Matching (Dart 3+)
71 
72Use sealed classes to model closed state hierarchies:
73 
74```dart
75sealed class AsyncState<T> {
76  const AsyncState();
77}
78 
79final class Loading<T> extends AsyncState<T> {
80  const Loading();
81}
82 
83final class Success<T> extends AsyncState<T> {
84  const Success(this.data);
85  final T data;
86}
87 
88final class Failure<T> extends AsyncState<T> {
89  const Failure(this.error);
90  final Object error;
91}
92```
93 
94Always use exhaustive `switch` with sealed types — no default/wildcard:
95 
96```dart
97// BAD
98if (state is Loading) { ... }
99 
100// GOOD
101return switch (state) {
102  Loading() => const CircularProgressIndicator(),
103  Success(:final data) => DataWidget(data),
104  Failure(:final error) => ErrorWidget(error.toString()),
105};
106```
107 
108## Error Handling
109 
110- Specify exception types in `on` clauses — never use bare `catch (e)`
111- Never catch `Error` subtypes — they indicate programming bugs
112- Use `Result`-style types or sealed classes for recoverable errors
113- Avoid using exceptions for control flow
114 
115```dart
116// BAD
117try {
118  await fetchUser();
119} catch (e) {
120  log(e.toString());
121}
122 
123// GOOD
124try {
125  await fetchUser();
126} on NetworkException catch (e) {
127  log('Network error: ${e.message}');
128} on NotFoundException {
129  handleNotFound();
130}
131```
132 
133## Async / Futures
134 
135- Always `await` Futures or explicitly call `unawaited()` to signal intentional fire-and-forget
136- Never mark a function `async` if it never `await`s anything
137- Use `Future.wait` / `Future.any` for concurrent operations
138- Check `context.mounted` before using `BuildContext` after any `await` (Flutter 3.7+)
139 
140```dart
141// BAD — ignoring Future
142fetchData(); // fire-and-forget without marking intent
143 
144// GOOD
145unawaited(fetchData()); // explicit fire-and-forget
146await fetchData();      // or properly awaited
147```
148 
149## Imports
150 
151- Use `package:` imports throughout — never relative imports (`../`) for cross-feature or cross-layer code
152- Order: `dart:` → external `package:` → internal `package:` (same package)
153- No unused imports — `dart analyze` enforces this with `unused_import`
154 
155## Code Generation
156 
157- Generated files (`.g.dart`, `.freezed.dart`, `.gr.dart`) must be committed or gitignored consistently — pick one strategy per project
158- Never manually edit generated files
159- Keep generator annotations (`@JsonSerializable`, `@freezed`, `@riverpod`, etc.) on the canonical source file only
160