Building Flutter Apps
Quick Start
flutter create --org com.yourcompany --project-name my_app ./my_app
cd my_app && flutter run
Skill Guides
| Area |
Guide |
Use When |
| Architecture |
architecture/SKILL.md |
Project structure, DI, repository pattern |
| UI Building |
ui/SKILL.md |
Layouts, Material 3, responsive design |
| State Management |
state-management/SKILL.md |
Riverpod, BLoC, state patterns |
| Testing |
testing/SKILL.md |
TDD, unit/widget tests, mocking |
| Project Setup |
project-setup.md |
New projects, pubspec, flavors |
| Navigation |
navigation.md |
go_router, deep links, transitions |
| Animations |
animations.md |
Implicit, explicit, Hero animations |
| Performance |
performance.md |
Optimization, profiling, app size |
| Deployment |
deployment.md |
App store builds, CI/CD, signing |
| Platform Integration |
platform-integration.md |
Platform channels, permissions |
| Packages |
packages.md |
Essential packages, creating plugins |
Feature-First Project Structure
lib/
├── main.dart
├── app.dart # MaterialApp configuration
├── core/ # Shared across all features
│ ├── providers/ # Core Riverpod providers
│ │ ├── api_client_provider.dart
│ │ └── shared_preferences_provider.dart
│ ├── network/api_client.dart
│ ├── error/failures.dart
│ ├── theme/app_theme.dart
│ └── widgets/ # Truly reusable widgets only
├── features/
│ ├── auth/
│ │ ├── data/
│ │ │ ├── datasources/
│ │ │ ├── models/
│ │ │ ├── repositories/auth_repository_impl.dart
│ │ │ └── providers/auth_repository_provider.dart
│ │ ├── domain/
│ │ │ ├── entities/
│ │ │ └── repositories/auth_repository.dart # Interface
│ │ └── presentation/
│ │ ├── providers/auth_provider.dart
│ │ ├── screens/
│ │ └── widgets/
│ ├── home/
│ │ ├── data/
│ │ ├── domain/
│ │ └── presentation/
│ └── [other_features]/
└── config/
├── routes.dart
└── environment.dart
Decision Guides
What to Build?
| Task |
Start Here |
| New project |
project-setup.md → architecture/ |
| New feature |
architecture/ → Write interface → TDD |
| UI screen |
ui/ → state-management/ |
| Fix performance |
performance.md |
| Release app |
deployment.md |
State Management Choice
| Scenario |
Use |
| Form input, toggle, local UI state |
setState |
| Single value shared across widgets |
ValueNotifier or StateProvider |
| Feature with loading/error states |
AsyncNotifierProvider (Riverpod) |
| Mutable state with business logic |
NotifierProvider (Riverpod) |
| Complex event flows, event tracking |
BLoC (alternative) |
Essential Commands
flutter pub get # Install dependencies
flutter run # Debug mode
flutter test # Run tests
flutter build apk --release # Android release
flutter build ipa --release # iOS release
flutter clean && flutter pub get # Reset project
# Riverpod code generation
dart run build_runner build --delete-conflicting-outputs
dart run build_runner watch --delete-conflicting-outputs
TDD Workflow (from AGENTS.md)
1. Interface First → Define contract in domain/repositories/
2. RED Phase → Write failing test, implementation throws UnimplementedError
3. GREEN Phase → Write minimum code to pass
4. REFACTOR → Clean up, add edge cases
1---2name: building-flutter-apps3description: Build production-ready Flutter apps for Android/iOS using feature-first architecture. Covers project setup, UI patterns, state management (Riverpod/BLoC), navigation (go_router), testing (TDD with mocktail), and deployment. Use when creating Flutter projects, implementing features, debugging Flutter issues, or making architectural decisions.4---5
6# Building Flutter Apps
7
8## Quick Start
9
10```bash
11flutter create --org com.yourcompany --project-name my_app ./my_app
12cd my_app && flutter run
13```
14
15## Skill Guides
16
17| Area | Guide | Use When |
18|------|-------|----------|
19| Architecture | [architecture/SKILL.md](architecture/SKILL.md) | Project structure, DI, repository pattern |
20| UI Building | [ui/SKILL.md](ui/SKILL.md) | Layouts, Material 3, responsive design |
21| State Management | [state-management/SKILL.md](state-management/SKILL.md) | Riverpod, BLoC, state patterns |
22| Testing | [testing/SKILL.md](testing/SKILL.md) | TDD, unit/widget tests, mocking |
23| Project Setup | [project-setup.md](project-setup.md) | New projects, pubspec, flavors |
24| Navigation | [navigation.md](navigation.md) | go_router, deep links, transitions |
25| Animations | [animations.md](animations.md) | Implicit, explicit, Hero animations |
26| Performance | [performance.md](performance.md) | Optimization, profiling, app size |
27| Deployment | [deployment.md](deployment.md) | App store builds, CI/CD, signing |
28| Platform Integration | [platform-integration.md](platform-integration.md) | Platform channels, permissions |
29| Packages | [packages.md](packages.md) | Essential packages, creating plugins |
30
31## Feature-First Project Structure
32
33```
34lib/
35├── main.dart
36├── app.dart # MaterialApp configuration
37├── core/ # Shared across all features
38│ ├── providers/ # Core Riverpod providers
39│ │ ├── api_client_provider.dart
40│ │ └── shared_preferences_provider.dart
41│ ├── network/api_client.dart
42│ ├── error/failures.dart
43│ ├── theme/app_theme.dart
44│ └── widgets/ # Truly reusable widgets only
45├── features/
46│ ├── auth/
47│ │ ├── data/
48│ │ │ ├── datasources/
49│ │ │ ├── models/
50│ │ │ ├── repositories/auth_repository_impl.dart
51│ │ │ └── providers/auth_repository_provider.dart
52│ │ ├── domain/
53│ │ │ ├── entities/
54│ │ │ └── repositories/auth_repository.dart # Interface
55│ │ └── presentation/
56│ │ ├── providers/auth_provider.dart
57│ │ ├── screens/
58│ │ └── widgets/
59│ ├── home/
60│ │ ├── data/
61│ │ ├── domain/
62│ │ └── presentation/
63│ └── [other_features]/
64└── config/
65 ├── routes.dart
66 └── environment.dart
67```
68
69## Decision Guides
70
71### What to Build?
72
73| Task | Start Here |
74|------|------------|
75| New project | [project-setup.md](project-setup.md) → [architecture/](architecture/SKILL.md) |
76| New feature | [architecture/](architecture/SKILL.md) → Write interface → TDD |
77| UI screen | [ui/](ui/SKILL.md) → [state-management/](state-management/SKILL.md) |
78| Fix performance | [performance.md](performance.md) |
79| Release app | [deployment.md](deployment.md) |
80
81### State Management Choice
82
83| Scenario | Use |
84|----------|-----|
85| Form input, toggle, local UI state | `setState` |
86| Single value shared across widgets | `ValueNotifier` or `StateProvider` |
87| Feature with loading/error states | `AsyncNotifierProvider` (Riverpod) |
88| Mutable state with business logic | `NotifierProvider` (Riverpod) |
89| Complex event flows, event tracking | `BLoC` (alternative) |
90
91## Essential Commands
92
93```bash
94flutter pub get # Install dependencies
95flutter run # Debug mode
96flutter test # Run tests
97flutter build apk --release # Android release
98flutter build ipa --release # iOS release
99flutter clean && flutter pub get # Reset project
100
101# Riverpod code generation
102dart run build_runner build --delete-conflicting-outputs
103dart run build_runner watch --delete-conflicting-outputs
104```
105
106## TDD Workflow (from AGENTS.md)
107
108```
1091. Interface First → Define contract in domain/repositories/
1102. RED Phase → Write failing test, implementation throws UnimplementedError
1113. GREEN Phase → Write minimum code to pass
1124. REFACTOR → Clean up, add edge cases
113```
majiayu000