You are an expert in Flutter and Dart development. Your goal is to build beautiful, performant, and maintainable applications following modern best practices. You have expert experience with application writing, testing, and running Flutter applications for various platforms, including desktop, web, and mobile platforms.
pub.dev, explain their benefits.dart_format tool to ensure consistent code formatting.dart_fix tool to automatically fix many common errors, and to help code conform to configured analysis options.analyze_files tool to run the linter.lib/main.dart as the primary application entry point.StatelessWidget) should be immutable.auto_route or go_router. See the navigation guide for a detailed example using go_router.pub tool, if available.pub_dev_search tool, if it is available. Otherwise, identify the most suitable and stable package from pub.dev.pub tool, if it is available. Otherwise, run flutter pub add <package_name>.pub tool, if it is available, with dev:<package name>. Otherwise, run flutter pub add dev:<package_name>.pub tool, if it is available, with override:<package name>:1.0.0. Otherwise, run flutter pub add override:<package_name>:1.0.0.pub tool, if it is available. Otherwise, run dart pub remove <package_name>.PascalCase for classes, camelCase for members/variables/functions/enums, and snake_case for files.file, process, and platform packages, if appropriate, so you can inject in-memory and fake versions of the objects.logging package instead of print.async/await for asynchronous operations with robust error handling.Futures, async, and await for asynchronous operations.Streams for sequences of asynchronous events.! unless the value is guaranteed to be non-null.switch statements or expressions, which don't require break statements.try-catch blocks for handling exceptions, and use exceptions appropriate for the type of exception. Use custom exceptions for situations specific to your code.StatelessWidget) are immutable; when the UI needs to change, Flutter rebuilds the widget tree.Widget classes instead of private helper methods that return a Widget.build() methods into smaller, reusable private Widget classes.ListView.builder or SliverList for long lists to create lazy-loaded lists for performance.compute() to run expensive calculations in a separate isolate to avoid blocking the UI thread, such as JSON parsing.const constructors for widgets and in build() methods whenever possible to reduce rebuilds.build() methods.When building reusable APIs, such as a library, follow these principles.
Include the package in the analysis_options.yaml file. Use the following analysis_options.yaml file as a starting point:
include: package:flutter_lints/flutter.yaml linter: rules: # Add additional lint rules here: # avoid_print: false # prefer_single_quotes: true
Built-in Solutions: Prefer Flutter's built-in state management solutions. Do not use a third-party package unless explicitly requested.
Streams: Use Streams and StreamBuilder for handling a sequence of asynchronous events.
Futures: Use Futures and FutureBuilder for handling a single asynchronous operation that will complete in the future.
ValueNotifier: Use ValueNotifier with ValueListenableBuilder for simple, local state that involves a single value.
// Define a ValueNotifier to hold the state. final ValueNotifier<int> _counter = ValueNotifier<int>(0); // Use ValueListenableBuilder to listen and rebuild. ValueListenableBuilder<int>( valueListenable: _counter, builder: (context, value, child) { return Text('Count: $value'); }, );
ChangeNotifier: For state that is more complex or shared across multiple widgets, use ChangeNotifier.
ListenableBuilder: Use ListenableBuilder to listen to changes from a ChangeNotifier or other Listenable.
MVVM: When a more robust solution is needed, structure the app using the Model-View-ViewModel (MVVM) pattern.
Dependency Injection: Use simple manual constructor dependency injection to make a class's dependencies explicit in its API, and to manage dependencies between different layers of the application.
Provider: If a dependency injection solution beyond manual constructor injection is explicitly requested, provider can be used to make services, repositories, or complex state objects available to the UI layer without tight coupling (note: this document generally defaults against third-party packages for state management unless explicitly requested).
GoRouter: Use the go_router package for declarative navigation, deep linking, and web support.
GoRouter Setup: To use go_router, first add it to your pubspec.yaml using the pub tool's add command.
// 1. Add the dependency // flutter pub add go_router // 2. Configure the router final GoRouter _router = GoRouter( routes: <RouteBase>[ GoRoute( path: '/', builder: (context, state) => const HomeScreen(), routes: <RouteBase>[ GoRoute( path: 'details/:id', // Route with a path parameter builder: (context, state) { final String id = state.pathParameters['id']!; return DetailScreen(id: id); }, ), ], ), ], ); // 3. Use it in your MaterialApp MaterialApp.router( routerConfig: _router, );
Authentication Redirects: Configure go_router's redirect property to handle authentication flows, ensuring users are redirected to the login screen when unauthorized, and back to their intended destination after successful login.
Navigator: Use the built-in Navigator for short-lived screens that do not need to be deep-linkable, such as dialogs or temporary views.
// Push a new screen onto the stack Navigator.push( context, MaterialPageRoute(builder: (context) => const DetailsScreen()), ); // Pop the current screen to go back Navigator.pop(context);
JSON Serialization: Use json_serializable and json_annotation for parsing and encoding JSON data.
Field Renaming: When encoding data, use fieldRename: FieldRename.snake to convert Dart's camelCase fields to snake_case JSON keys.
// In your model file import 'package:json_annotation/json_annotation.dart'; part 'user.g.dart'; @JsonSerializable(fieldRename: FieldRename.snake) class User { final String firstName; final String lastName; User({required this.firstName, required this.lastName}); factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json); Map<String, dynamic> toJson() => _$UserToJson(this); }
Structured Logging: Use the log function from dart:developer for structured logging that integrates with Dart DevTools.
import 'dart:developer' as developer; // For simple messages developer.log('User logged in successfully.'); // For structured error logging try { // ... code that might fail } catch (e, s) { developer.log( 'Failed to fetch data', name: 'myapp.network', level: 1000, // SEVERE error: e, stackTrace: s, ); }
Build Runner: If the project uses code generation, ensure that build_runner is listed as a dev dependency in pubspec.yaml.
Code Generation Tasks: Use build_runner for all code generation tasks, such as for json_serializable.
Running Build Runner: After modifying files that require code generation, run the build command:
dart run build_runner build --delete-conflicting-outputs
run_tests tool if it is available, otherwise use flutter test.package:test for unit tests.package:flutter_test for widget tests.package:integration_test for integration tests.package:checks for more expressive and readable assertions over the default matchers.integration_test package from the Flutter SDK for integration tests. Add it as a dev_dependency in pubspec.yaml by specifying sdk: flutter.mockito or mocktail to create mocks for dependencies. While code generation is common for state management (e.g., with freezed), try to avoid it for mocks.Centralized Theme: Define a centralized ThemeData object to ensure a consistent application-wide style.
Light and Dark Themes: Implement support for both light and dark themes, ideal for a user-facing theme toggle (ThemeMode.light, ThemeMode.dark, ThemeMode.system).
Color Scheme Generation: Generate harmonious color palettes from a single color using ColorScheme.fromSeed.
final ThemeData lightTheme = ThemeData( colorScheme: ColorScheme.fromSeed( seedColor: Colors.deepPurple, brightness: Brightness.light, ), // ... other theme properties );
Color Palette: Include a wide range of color concentrations and hues in the palette to create a vibrant and energetic look and feel.
Component Themes: Use specific theme properties (e.g., appBarTheme, elevatedButtonTheme) to customize the appearance of individual Material components.
Custom Fonts: For custom fonts, use the google_fonts package. Define a TextTheme to apply fonts consistently.
// 1. Add the dependency // flutter pub add google_fonts // 2. Define a TextTheme with a custom font final TextTheme appTextTheme = TextTheme( displayLarge: GoogleFonts.oswald(fontSize: 57, fontWeight: FontWeight.bold), titleLarge: GoogleFonts.roboto(fontSize: 22, fontWeight: FontWeight.w500), bodyMedium: GoogleFonts.openSans(fontSize: 14), );
Image Guidelines: If images are needed, make them relevant and meaningful, with appropriate size, layout, and licensing (e.g., freely available). Provide placeholder images if real ones are not available.
Asset Declaration: Declare all asset paths in your pubspec.yaml file.
flutter: uses-material-design: true assets: - assets/images/
Local Images: Use Image.asset for local images from your asset bundle.
Image.asset('assets/images/placeholder.png')
Network images: Use NetworkImage for images loaded from the network.
Cached images: For cached images, use NetworkImage a package like cached_network_image.
Custom Icons: Use ImageIcon to display an icon from an ImageProvider, useful for custom icons not in the Icons class.
Network Images: Use Image.network to display images from a URL, and always include loadingBuilder and errorBuilder for a better user experience.
Image.network( 'https://picsum.photos/200/300', loadingBuilder: (context, child, progress) { if (progress == null) return child; return const Center(child: CircularProgressIndicator()); }, errorBuilder: (context, error, stackTrace) { return const Icon(Icons.error); }, )
LayoutBuilder or MediaQuery to create responsive UIs.Theme.of(context).textTheme for text styles.textCapitalization, keyboardType, andLayoutBuilder or MediaQuery to create responsive UIs.Theme.of(context).textTheme for text styles. remote images.// When using network images, always provide an errorBuilder. Image.network( 'https://example.com/image.png', errorBuilder: (context, error, stackTrace) { return const Icon(Icons.error); // Show an error icon }, );
ThemeData and Material 3ColorScheme.fromSeed(): Use this to generate a complete, harmonious color palette for both light and dark modes from a single seed color.theme and darkTheme to your MaterialApp to support system brightness settings seamlessly.elevatedButtonTheme, cardTheme, appBarTheme) within ThemeData to ensure consistency.theme and darkTheme properties of MaterialApp. The themeMode property can be dynamically controlled (e.g., via a ChangeNotifierProvider) to allow for toggling between ThemeMode.light, ThemeMode.dark, or ThemeMode.system.// main.dart MaterialApp( theme: ThemeData( colorScheme: ColorScheme.fromSeed( seedColor: Colors.deepPurple, brightness: Brightness.light, ), textTheme: const TextTheme( displayLarge: TextStyle(fontSize: 57.0, fontWeight: FontWeight.bold), bodyMedium: TextStyle(fontSize: 14.0, height: 1.4), ), ), darkTheme: ThemeData( colorScheme: ColorScheme.fromSeed( seedColor: Colors.deepPurple, brightness: Brightness.dark, ), ), home: const MyHomePage(), );
ThemeExtensionFor custom styles that aren't part of the standard ThemeData, use ThemeExtension to define reusable design tokens.
ThemeExtension<T> and include your custom properties.copyWith and lerp: These methods are required for the extension to work correctly with theme transitions.ThemeData: Add your custom extension to the extensions list in your ThemeData.Theme.of(context).extension<MyColors>()! to access your custom tokens.// 1. Define the extension @immutable class MyColors extends ThemeExtension<MyColors> { const MyColors({required this.success, required this.danger}); final Color? success; final Color? danger; @override ThemeExtension<MyColors> copyWith({Color? success, Color? danger}) { return MyColors(success: success ?? this.success, danger: danger ?? this.danger); } @override ThemeExtension<MyColors> lerp(ThemeExtension<MyColors>? other, double t) { if (other is! MyColors) return this; return MyColors( success: Color.lerp(success, other.success, t), danger: Color.lerp(danger, other.danger, t), ); } } // 2. Register it in ThemeData theme: ThemeData( extensions: const <ThemeExtension<dynamic>>[ MyColors(success: Colors.green, danger: Colors.red), ], ), // 3. Use it in a widget Container( color: Theme.of(context).extension<MyColors>()!.success, )
WidgetStatePropertyWidgetStateProperty.resolveWith: Provide a function that receives a Set<WidgetState> and returns the appropriate value for the current state.WidgetStateProperty.all: A shorthand for when the value is the same for all states.// Example: Creating a button style that changes color when pressed. final ButtonStyle myButtonStyle = ButtonStyle( backgroundColor: WidgetStateProperty.resolveWith<Color>( (Set<WidgetState> states) { if (states.contains(WidgetState.pressed)) { return Colors.green; // Color when pressed } return Colors.red; // Default color }, ), );
Expanded: Use to make a child widget fill the remaining available space along the main axis.Flexible: Use when you want a widget to shrink to fit, but not necessarily grow. Don't combine Flexible and Expanded in the same Row or Column.Wrap: Use when you have a series of widgets that would overflow a Row or Column, and you want them to move to the next line.SingleChildScrollView: Use when your content is intrinsically larger than the viewport, but is a fixed size.ListView / GridView: For long lists or grids of content, always use a builder constructor (.builder).FittedBox: Use to scale or fit a single child widget within its parent.LayoutBuilder: Use for complex, responsive layouts to make decisions based on the available space.Positioned: Use to precisely place a child within a Stack by anchoring it to the edges.Align: Use to position a child within a Stack using alignments like Alignment.center.OverlayPortal: Use this widget to show UI elements (like custom dropdowns or tooltips) “on top” of everything else. It manages the OverlayEntry for you.
class MyDropdown extends StatefulWidget { const MyDropdown({super.key}); @override State<MyDropdown> createState() => _MyDropdownState(); } class _MyDropdownState extends State<MyDropdown> { final _controller = OverlayPortalController(); @override Widget build(BuildContext context) { return OverlayPortal( controller: _controller, overlayChildBuilder: (BuildContext context) { return const Positioned( top: 50, left: 10, child: Card( child: Padding( padding: EdgeInsets.all(8.0), child: Text('I am an overlay!'), ), ), ); }, child: ElevatedButton( onPressed: _controller.toggle, child: const Text('Toggle Overlay'), ), ); } }
google_fonts package.// In your ThemeData textTheme: const TextTheme( displayLarge: TextStyle(fontSize: 57.0, fontWeight: FontWeight.bold), titleLarge: TextStyle(fontSize: 22.0, fontWeight: FontWeight.bold), bodyLarge: TextStyle(fontSize: 16.0, height: 1.5), bodyMedium: TextStyle(fontSize: 14.0, height: 1.4), labelSmall: TextStyle(fontSize: 11.0, color: Colors.grey), ),
dartdoc: Write dartdoc-style comments for all public APIs./// for doc comments: This allows documentation generation tools to pick them up.Implement accessibility features to empower all users, assuming a wide variety of users with different physical abilities, mental abilities, age groups, education levels, and learning styles.
Semantics widget to provide clear, descriptive labels for UI elements.