Dart Rules

Dart/Flutter Rules

These rules come from app/rules/dart/ in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Dart/Flutter. Apply them when writing or reviewing Dart/Flutter code.

Dart Coding Style

Naming

• PascalCase: classes, enums, typedefs, extensions, mixins.
• camelCase: variables, functions, methods, parameters, named constants.
• snake_case: libraries, packages, directories, source files.
• UPPER_SNAKE: not used in Dart. Use camelCase for constants.
• Prefix private members with _: _internalState, _helper().

Null Safety

• Enable sound null safety (default since Dart 2.12).
• Use ? types only when null is semantically meaningful.
• Use ! operator sparingly. Prefer null checks or ?? fallback.
• Use late keyword only when initialization is guaranteed before access.
• Use required keyword for mandatory named parameters.

Classes

• Use const constructors for immutable classes.
• Use factory constructors for caching, subtype selection, or validation.
• Use named constructors for clarity: Point.fromJson(json).
• Use final fields for immutable properties.
• Use @immutable annotation on classes that should be immutable.

Functions

• Use named parameters for functions with >2 parameters.
• Use required for mandatory named parameters.
• Use default values for optional parameters.
• Use fat arrow (=>) for single-expression functions.
• Always specify return types for public functions.

Collections

• Use collection literals: [], {}, <String, int>{}.
• Use if and for inside collection literals for conditional/iterative building.
• Use spread operator: [...list1, ...list2].
• Use whereType<T>() for type-safe filtering.
• Prefer const collections when values are known at compile time.

Async

• Use async/await for all asynchronous operations.
• Return Future<T> from async functions. Never return void.
• Use Stream<T> for continuous data (events, real-time updates).
• Use Future.wait() for concurrent independent operations.
• Use Completer<T> only when wrapping callback-based APIs.

Imports

• Order: dart: SDK, package: external, relative project imports.
• Use show/hide to limit import scope when names conflict.
• Use as prefix for namespace conflicts: import 'package:foo/foo.dart' as foo.
• Prefer relative imports within the same package.

Formatting

• Use dart format (line length 80) for consistent formatting.
• Use dart analyze for static analysis with default lint rules.
• Use analysis_options.yaml with recommended lints: flutter_lints or lints.
• Use trailing commas in multi-line argument lists for cleaner diffs.

Dart Frameworks

Flutter

• Use StatelessWidget by default. Use StatefulWidget only for local state.
• Use const constructors and const widgets for build optimization.
• Use Key parameters for widgets in lists for correct diffing.
• Extract large build() methods into smaller widget classes (not methods).
• Use Theme.of(context) and TextTheme for consistent styling.

Navigation

• Use GoRouter for declarative, type-safe routing.
• Define routes as constants: static const String home = '/home'.
• Use ShellRoute for persistent navigation bars across routes.
• Use context.go() for navigation, context.push() for stacking.
• Pass arguments via path parameters or extra for complex objects.

Networking

• Use dio for HTTP with interceptors, retry, and cancellation.
• Use retrofit (code gen) for type-safe REST client definitions.
• Use interceptors for auth token injection and refresh logic.
• Set timeouts on every request: connectTimeout, receiveTimeout.
• Use CancelToken for cancelling in-flight requests on navigation.

JSON Serialization

• Use json_serializable (+ build_runner) for generated fromJson/toJson. Default fieldRename: FieldRename.none uses Dart property names as-is — combined with Effective Dart lowerCamelCase, this produces camelCase JSON keys with zero configuration.
• Flutter docs recommend: "best if both server and client follow the same naming strategy" (Flutter — JSON and serialization). When they do, no mapping is needed.
• When server uses a different convention, prefer @JsonSerializable(fieldRename: FieldRename.snake) at the class level (or globally in build.yaml) over sprinkling @JsonKey(name:) on every field. Community recommendation from the json_serializable docs and pub.dev guides.
• Use individual @JsonKey(name: '...') only for exceptional cases: external API with mixed conventions, reserved Dart keyword collision (class, is, new), or legacy field rename during deprecation window. Document the reason in a comment.
• For enum / status / permission values on the wire: UPPER_SNAKE_CASE is the cross-language community consensus (see common/coding-style.md — JSON Wire Format Conventions). Dart enum case names themselves stay lowerCamelCase per Effective Dart; map them to uppercase strings in fromJson/toJson (value.toUpperCase() + switch).
• Write unit tests asserting both directions (fromJson + toJson) with explicit expected keys. Catches contract drift at CI time.

Local Storage

• Use shared_preferences for simple key-value persistence.
• Use drift (formerly Moor) for type-safe SQLite with reactive queries.
• Use hive for fast, lightweight NoSQL local storage.
• Use flutter_secure_storage for sensitive data (tokens, passwords).
• Never store secrets in shared_preferences (not encrypted).

Dependency Injection

• Use get_it for service locator pattern. Register at app startup.
• Use injectable (code gen) for automatic registration from annotations.
• Use Riverpod providers as DI containers for testable architecture.
• Register singletons for services, factories for per-use instances.

Platform Channels

• Use MethodChannel for invoking native (iOS/Android) code.
• Use EventChannel for streaming data from native to Dart.
• Use Pigeon (code gen) for type-safe platform channel definitions.
• Handle MissingPluginException gracefully on unsupported platforms.

Testing Frameworks

• Use flutter_test for widget tests with WidgetTester.
• Use integration_test package for full app integration tests.
• Use patrol for native-aware integration testing (permissions, notifications).
• Use golden_toolkit for advanced visual regression testing.

Build and CI

• Use flutter build with --release and --dart-define for env configuration.
• Use flavors (--flavor) for dev/staging/prod build variants.
• Use flutter analyze in CI for static analysis enforcement.
• Use flutter test --coverage with lcov for coverage reporting.

Dart Patterns

Error Handling

• Use typed exceptions for domain errors: class UserNotFoundException implements Exception.
• Use try-catch with specific exception types. Avoid bare catch (e).
• Use rethrow to preserve stack trace when re-raising exceptions.
• Use Result<T, E> pattern (e.g., dartz Either) for expected failures.
• Use Future.catchError() only when async/await is not applicable.

State Management (Flutter)

• Use Riverpod for compile-safe, testable state management.
• Use BLoC pattern for event-driven state with clear input/output.
• Use ChangeNotifier / ValueNotifier for simple local state.
• Use StateNotifier (Riverpod) for immutable state transitions.
• Keep state classes immutable. Use copyWith() for updates.

Riverpod

• Use @riverpod annotation (code gen) for provider definitions.
• Use ref.watch() for reactive dependencies. Use ref.read() for one-time access.
• Use AsyncNotifier for async state management.
• Use autoDispose for providers that should clean up when unused.
• Use family modifier for parameterized providers.

BLoC Pattern

• Separate events (input), states (output), and logic (bloc).
• Use sealed class for events and states (exhaustive switch).
• Use Emitter<State> for emitting state transitions.
• Use transformEvents() for debouncing search inputs.
• Use BlocObserver for global logging and error tracking.

Repository Pattern

• Abstract data sources behind repository interfaces.
• Repositories return domain models, not DTOs or raw data.
• Use Future<T> for single values, Stream<T> for real-time updates.
• Cache data in repository layer when appropriate.
• Inject repositories via constructor. Use Riverpod/GetIt for DI.

Freezed (Code Generation)

• Use @freezed for immutable data classes with copyWith, equality, toString.
• Use @freezed sealed unions for state modeling: factory State.loading().
• Use when() / map() for exhaustive pattern matching on freezed unions.
• Run dart run build_runner build after modifying freezed classes.