Flutter Project

---
applyTo: "**/*.dart"
---

# Flutter Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up the latest Flutter documentation: https://docs.flutter.dev
- Use Flutter 3.x for cross-platform mobile development
- Write declarative UI with widget composition
- Use state management solutions (Provider, Riverpod, Bloc)
- Follow Flutter and Dart style guides
- Leverage Material Design or Cupertino widgets

**Core Principles:**

- Everything is a widget in Flutter
- Use StatelessWidget for static UI, StatefulWidget for dynamic UI
- Implement proper widget composition and reusability
- Use const constructors for performance
- Follow single responsibility principle for widgets
- Use meaningful widget names

**State Management:**

- Use Provider or Riverpod for dependency injection and state
- Implement Bloc pattern for complex state logic
- Use ChangeNotifier for simple state management
- Leverage ValueNotifier for lightweight state
- Use setState only for local widget state
- Implement proper state separation (UI vs business logic)

**Widget Design:**

- Build small, focused, reusable widgets
- Use composition over inheritance
- Extract complex widgets into separate classes
- Use Builder widgets for context-dependent UI
- Implement proper key usage for widget identity
- Use CustomPaint for custom graphics

**Navigation:**

- Use Navigator 2.0 with declarative routing
- Implement named routes for deep linking
- Use go_router or auto_route for advanced routing
- Handle navigation stack properly
- Implement proper back button handling

**Async Programming:**

- Use FutureBuilder for one-time async operations
- Use StreamBuilder for continuous data streams
- Implement async/await for asynchronous code
- Handle errors with try-catch in async functions
- Use isolates for heavy computations

**Performance:**

- Use const constructors wherever possible
- Implement RepaintBoundary for complex widgets
- Use ListView.builder for large lists
- Avoid rebuilding entire widget trees
- Profile with Flutter DevTools
- Implement lazy loading for data

**Styling:**

- Use Theme for consistent styling across app
- Implement custom themes with ThemeData
- Use MediaQuery for responsive design
- Follow Material Design or Cupertino guidelines
- Create reusable style constants

**Networking:**

- Use dio or http package for HTTP requests
- Implement proper error handling
- Use models with json_serializable for serialization
- Implement retry logic and timeout handling
- Cache network responses when appropriate

**Testing:**

- Write widget tests for UI components
- Implement unit tests for business logic
- Use integration tests for user flows
- Mock dependencies with mockito
- Use golden tests for visual regression

**Platform Integration:**

- Use platform channels for native code integration
- Implement method channels for two-way communication
- Use platform-specific widgets when needed
- Handle platform permissions properly
- Test on both iOS and Android

**Summary:**

> For all Flutter work, always use the fetch tool to look up the latest documentation from https://docs.flutter.dev. Build beautiful, natively compiled cross-platform applications.