| name | flutter-best-practices |
| description | Flutter performance optimization guidelines. This skill should be used when writing, reviewing, or refactoring Flutter/Dart code to ensure optimal performance patterns. Triggers on tasks involving Flutter widgets, state management, list rendering, image optimization, animations, or app performance improvements. |
Flutter Best Practices
Comprehensive performance optimization guide for Flutter applications. Contains 40+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
When to Apply
Reference these guidelines when:
- Writing new Flutter widgets or screens
- Implementing list rendering (ListView, GridView)
- Optimizing widget builds and state management
- Reviewing code for performance issues
- Refactoring existing Flutter/Dart code
- Setting up navigation with GoRouter
- Reducing app size or improving startup time
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|
| 1 | Widget Build Optimization | CRITICAL | build- |
| 2 | List & Scroll Performance | CRITICAL | list- |
| 3 | State Management | HIGH | state- |
| 4 | Image & Asset Optimization | HIGH | image- |
| 5 | Animation Performance | MEDIUM | anim- |
| 6 | Navigation & Routing | MEDIUM | nav- |
| 7 | Memory Management | MEDIUM | memory- |
| 8 | App Size & Startup | LOW-MEDIUM | app- |
Quick Reference
1. Widget Build Optimization (CRITICAL)
build-const-widgets - Use const constructors for static widgets
build-split-widgets - Split large widgets into smaller ones
build-avoid-rebuild - Avoid unnecessary widget rebuilds
build-keys - Use keys correctly for widget identity
build-repaint-boundary - Isolate expensive paint operations
build-builder-pattern - Use Builder pattern for context access
2. List & Scroll Performance (CRITICAL)
list-builder - Use ListView.builder for large lists
list-item-extent - Specify itemExtent for fixed-height items
list-cache-extent - Configure cacheExtent appropriately
list-sliver - Use Slivers for complex scrolling layouts
list-keep-alive - Use AutomaticKeepAliveClientMixin wisely
list-separated - Use ListView.separated for dividers
3. State Management (HIGH)
state-provider - Use Provider/Riverpod for dependency injection
state-selector - Use Selector/select for granular rebuilds
state-notifier - Prefer ValueNotifier for simple state
state-inherited - Understand InheritedWidget properly
state-bloc-events - Structure BLoC events correctly
state-immutable - Keep state objects immutable
4. Image & Asset Optimization (HIGH)
image-cached - Use cached_network_image for remote images
image-precache - Precache images for smooth display
image-resize - Load images at display size
image-placeholder - Use placeholders and error widgets
image-format - Use WebP format for smaller sizes
image-memory - Dispose image resources properly
5. Animation Performance (MEDIUM)
anim-implicit - Prefer implicit animations when possible
anim-ticker - Use TickerProviderStateMixin correctly
anim-transform - Use Transform instead of Container
anim-opacity - Use AnimatedOpacity for fade effects
anim-hero - Implement Hero animations properly
anim-custom-painter - Optimize CustomPainter repaints
6. Navigation & Routing (MEDIUM)
nav-go-router - Use GoRouter for declarative routing
nav-deep-links - Configure deep linking properly
nav-transitions - Customize page transitions
nav-nested - Handle nested navigation correctly
nav-guards - Implement route guards for auth
7. Memory Management (MEDIUM)
memory-dispose - Always dispose controllers and streams
memory-listeners - Remove listeners on dispose
memory-isolates - Use isolates for heavy computation
memory-weak-refs - Use WeakReference for caches
8. App Size & Startup (LOW-MEDIUM)
app-tree-shake - Enable icon tree shaking
app-deferred - Use deferred loading for features
app-split-debug - Split debug info for smaller builds
app-obfuscate - Obfuscate Dart code in release
app-native-splash - Configure native splash screen
How to Use
Read individual rule files for detailed explanations and code examples:
rules/build-const-widgets.md
rules/list-builder.md
rules/_sections.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md