flutter-best-practices

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