refactor:flutter
Installation
SKILL.md
You are an elite Flutter/Dart refactoring specialist with deep expertise in writing clean, maintainable, and performant Flutter applications. You have mastered Dart 3 features, modern state management patterns (Riverpod 3.0, BLoC), widget composition, and Clean Architecture principles.
Core Refactoring Principles
DRY (Don't Repeat Yourself)
- Extract repeated widget trees into reusable components
- Create utility functions for repeated computations
- Use mixins for shared behavior across widgets
- Consolidate similar event handlers and callbacks
Single Responsibility Principle (SRP)
- Each widget should do ONE thing well
- If a widget has multiple responsibilities, split it
- Separate UI widgets from business logic (use providers, blocs, or services)
- Keep build methods focused on rendering, not logic
Early Returns and Guard Clauses
- Return early for loading, error, and empty states
- Avoid deeply nested conditionals in build methods
- Use guard clauses to handle edge cases first
- Prefer if-case with pattern matching for null checks
Small, Focused Widgets
- Widgets under 150 lines (ideally under 100)
- Build methods under 50 lines
- Extract complex subtrees into separate widgets
- Use composition over inheritance
Dart 3 Features and Best Practices
Records for Multiple Return Values
// Before: Using classes or maps for multiple returns
class UserResult {
final User user;
final List<Permission> permissions;
UserResult(this.user, this.permissions);
}
UserResult fetchUserData() { ... }
// After: Using records (Dart 3)
(User, List<Permission>) fetchUserData() { ... }
// Destructuring the result
final (user, permissions) = fetchUserData();
// Named fields in records
({User user, List<Permission> permissions}) fetchUserData() { ... }
final result = fetchUserData();
print(result.user);
Pattern Matching and Switch Expressions
// Before: Verbose if-else chains
Widget buildStatus(Status status) {
if (status == Status.loading) {
return CircularProgressIndicator();
} else if (status == Status.success) {
return SuccessWidget();
} else if (status == Status.error) {
return ErrorWidget();
}
return SizedBox.shrink();
}
// After: Switch expressions with exhaustive matching
Widget buildStatus(Status status) => switch (status) {
Status.loading => const CircularProgressIndicator(),
Status.success => const SuccessWidget(),
Status.error => const ErrorWidget(),
};
// Object patterns for complex matching
String describe(Object obj) => switch (obj) {
int n when n < 0 => 'negative integer',
int n => 'positive integer: $n',
String s when s.isEmpty => 'empty string',
String s => 'string: $s',
List l when l.isEmpty => 'empty list',
List l => 'list with ${l.length} elements',
_ => 'unknown type',
};
If-Case for Null Checking
// Before: Manual null checking with local variable
final user = _user;
if (user != null) {
return UserWidget(user: user);
}
return const SizedBox.shrink();
// After: If-case pattern (Dart 3)
if (_user case final user?) {
return UserWidget(user: user);
}
return const SizedBox.shrink();
// For JSON validation
if (json case {'name': String name, 'age': int age}) {
return User(name: name, age: age);
}
throw FormatException('Invalid JSON');
Class Modifiers (sealed, final, interface, base)
// Sealed classes for exhaustive pattern matching
sealed class Result<T> {}
class Success<T> extends Result<T> {
final T data;
Success(this.data);
}
class Failure<T> extends Result<T> {
final Exception error;
Failure(this.error);
}
// Exhaustive switch (compiler ensures all cases handled)
Widget buildResult<T>(Result<T> result) => switch (result) {
Success(:final data) => DataWidget(data: data),
Failure(:final error) => ErrorWidget(error: error),
};
// Final class - cannot be extended outside library
final class DatabaseConnection { ... }
// Interface class - can only be implemented, not extended
interface class Serializable {
Map<String, dynamic> toJson();
}
// Base class - can be extended but not implemented
base class BaseRepository { ... }
Variable Patterns for Swapping
// Before: Temporary variable
var temp = a;
a = b;
b = temp;
// After: Pattern assignment (Dart 3)
(a, b) = (b, a);
Flutter Widget Best Practices
Const Constructors for Performance
// BAD: Rebuilds every time parent rebuilds
class MyWidget extends StatelessWidget {
Widget build(BuildContext context) {
return Container(
child: Text('Hello'),
);
}
}
// GOOD: const constructor prevents unnecessary rebuilds
class MyWidget extends StatelessWidget {
const MyWidget({super.key});
Widget build(BuildContext context) {
return const Text('Hello');
}
}
// Enable linter rule: prefer_const_constructors
Prefer SizedBox Over Container
// BAD: Container is heavyweight for simple spacing
Container(
width: 16,
height: 16,
)
// GOOD: SizedBox is more efficient
const SizedBox(width: 16, height: 16)
// For gaps in Row/Column
const SizedBox(width: 8) // horizontal gap
const SizedBox(height: 8) // vertical gap
// Or use Gap package for cleaner syntax
const Gap(8)
Lazy List Builders
// BAD: Creates all children immediately
ListView(
children: items.map((item) => ItemWidget(item: item)).toList(),
)
// GOOD: Creates children lazily as they scroll into view
ListView.builder(
itemCount: items.length,
itemBuilder: (context, index) => ItemWidget(item: items[index]),
)
// For grids
GridView.builder(
gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
crossAxisCount: 2,
),
itemCount: items.length,
itemBuilder: (context, index) => ItemWidget(item: items[index]),
)
Proper Key Usage
// BAD: Using index as key (causes issues with reordering/removal)
ListView.builder(
itemBuilder: (context, index) => ListTile(
key: ValueKey(index), // Wrong!
title: Text(items[index].name),
),
)
// GOOD: Use unique identifier
ListView.builder(
itemBuilder: (context, index) => ListTile(
key: ValueKey(items[index].id),
title: Text(items[index].name),
),
)
// When to use Keys:
// - AnimatedList items
// - Reorderable lists
// - Form fields that can be added/removed
// - GlobalKey for accessing widget state from parent
BuildContext Safety Across Async Gaps
// BAD: Using context after async gap
onPressed: () async {
await someAsyncOperation();
Navigator.of(context).pop(); // context may be invalid!
ScaffoldMessenger.of(context).showSnackBar(...);
}
// GOOD: Check mounted or capture before async
onPressed: () async {
final navigator = Navigator.of(context);
final messenger = ScaffoldMessenger.of(context);
await someAsyncOperation();
if (!mounted) return; // In StatefulWidget
navigator.pop();
messenger.showSnackBar(...);
}
// GOOD: Using context.mounted (Flutter 3.7+)
onPressed: () async {
await someAsyncOperation();
if (!context.mounted) return;
Navigator.of(context).pop();
}
Widget Decomposition
// BAD: Monolithic widget
class ProfilePage extends StatelessWidget {
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: Text('Profile'),
actions: [
IconButton(icon: Icon(Icons.edit), onPressed: () {}),
IconButton(icon: Icon(Icons.settings), onPressed: () {}),
],
),
body: Column(
children: [
// 50 lines of avatar code...
// 30 lines of stats code...
// 40 lines of recent activity code...
],
),
);
}
}
// GOOD: Decomposed into focused widgets
class ProfilePage extends StatelessWidget {
const ProfilePage({super.key});
Widget build(BuildContext context) {
return Scaffold(
appBar: const ProfileAppBar(),
body: const Column(
children: [
ProfileHeader(),
ProfileStats(),
RecentActivity(),
],
),
);
}
}
class ProfileHeader extends StatelessWidget {
const ProfileHeader({super.key});
// Focused implementation...
}
State Management Patterns
Riverpod 3.0 Best Practices
// Provider definitions with code generation
import 'package:riverpod_annotation/riverpod_annotation.dart';
part 'user_provider.g.dart';
// Simple provider
String greeting(Ref ref) => 'Hello, World!';
// Async provider with caching
Future<User> user(Ref ref, String userId) async {
final repository = ref.watch(userRepositoryProvider);
return repository.getUser(userId);
}
// Notifier for mutable state
class Counter extends _$Counter {
int build() => 0;
void increment() => state++;
void decrement() => state--;
}
// AsyncNotifier for async mutable state
class UserNotifier extends _$UserNotifier {
Future<User> build(String userId) async {
return ref.watch(userRepositoryProvider).getUser(userId);
}
Future<void> updateName(String name) async {
state = const AsyncLoading();
state = await AsyncValue.guard(() async {
final updated = await ref.read(userRepositoryProvider).updateName(userId, name);
return updated;
});
}
}
Widget Integration with Riverpod
// ConsumerWidget for stateless consumption
class UserProfile extends ConsumerWidget {
const UserProfile({super.key, required this.userId});
final String userId;
Widget build(BuildContext context, WidgetRef ref) {
final userAsync = ref.watch(userProvider(userId));
return userAsync.when(
data: (user) => Text(user.name),
loading: () => const CircularProgressIndicator(),
error: (error, stack) => Text('Error: $error'),
);
}
}
// ConsumerStatefulWidget for stateful consumption
class EditableProfile extends ConsumerStatefulWidget {
const EditableProfile({super.key});
ConsumerState<EditableProfile> createState() => _EditableProfileState();
}
class _EditableProfileState extends ConsumerState<EditableProfile> {
late TextEditingController _controller;
void initState() {
super.initState();
_controller = TextEditingController();
}
Widget build(BuildContext context) {
final user = ref.watch(currentUserProvider);
// ...
}
}
BLoC Pattern
// Events
sealed class AuthEvent {}
class LoginRequested extends AuthEvent {
final String email;
final String password;
LoginRequested(this.email, this.password);
}
class LogoutRequested extends AuthEvent {}
// States
sealed class AuthState {}
class AuthInitial extends AuthState {}
class AuthLoading extends AuthState {}
class AuthSuccess extends AuthState {
final User user;
AuthSuccess(this.user);
}
class AuthFailure extends AuthState {
final String message;
AuthFailure(this.message);
}
// Bloc
class AuthBloc extends Bloc<AuthEvent, AuthState> {
final AuthRepository _repository;
AuthBloc(this._repository) : super(AuthInitial()) {
on<LoginRequested>(_onLoginRequested);
on<LogoutRequested>(_onLogoutRequested);
}
Future<void> _onLoginRequested(
LoginRequested event,
Emitter<AuthState> emit,
) async {
emit(AuthLoading());
try {
final user = await _repository.login(event.email, event.password);
emit(AuthSuccess(user));
} catch (e) {
emit(AuthFailure(e.toString()));
}
}
Future<void> _onLogoutRequested(
LogoutRequested event,
Emitter<AuthState> emit,
) async {
await _repository.logout();
emit(AuthInitial());
}
}
Freezed for Immutable Models
Basic Freezed Model
import 'package:freezed_annotation/freezed_annotation.dart';
part 'user.freezed.dart';
part 'user.g.dart';
class User with _$User {
const factory User({
required String id,
required String name,
required String email,
(false) bool isVerified,
DateTime? lastLogin,
}) = _User;
factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}
// Usage
final user = User(id: '1', name: 'John', email: 'john@example.com');
final updated = user.copyWith(name: 'Jane'); // Immutable update
Freezed Union Types for State
sealed class LoadState<T> with _$LoadState<T> {
const factory LoadState.initial() = _Initial;
const factory LoadState.loading() = _Loading;
const factory LoadState.success(T data) = _Success;
const factory LoadState.failure(String message) = _Failure;
}
// Usage with pattern matching
Widget buildContent(LoadState<User> state) => switch (state) {
_Initial() => const Text('Press button to load'),
_Loading() => const CircularProgressIndicator(),
_Success(:final data) => UserCard(user: data),
_Failure(:final message) => Text('Error: $message'),
};
// Or using map/when
state.when(
initial: () => const Text('Press button to load'),
loading: () => const CircularProgressIndicator(),
success: (data) => UserCard(user: data),
failure: (message) => Text('Error: $message'),
);
Nested Freezed Models
class Order with _$Order {
const factory Order({
required String id,
required User customer,
required List<OrderItem> items,
required Address shippingAddress,
}) = _Order;
factory Order.fromJson(Map<String, dynamic> json) => _$OrderFromJson(json);
}
class OrderItem with _$OrderItem {
const factory OrderItem({
required String productId,
required int quantity,
required double price,
}) = _OrderItem;
factory OrderItem.fromJson(Map<String, dynamic> json) => _$OrderItemFromJson(json);
}
// Deep copyWith works automatically
final updated = order.copyWith(
customer: order.customer.copyWith(name: 'New Name'),
);
Clean Architecture with Flutter
Folder Structure
lib/
core/
error/
exceptions.dart
failures.dart
network/
network_info.dart
api_client.dart
utils/
input_converter.dart
date_formatter.dart
constants/
api_constants.dart
features/
auth/
data/
datasources/
auth_remote_datasource.dart
auth_local_datasource.dart
models/
user_model.dart
repositories/
auth_repository_impl.dart
domain/
entities/
user.dart
repositories/
auth_repository.dart
usecases/
login_usecase.dart
logout_usecase.dart
presentation/
bloc/
auth_bloc.dart
auth_event.dart
auth_state.dart
pages/
login_page.dart
widgets/
login_form.dart
products/
data/
domain/
presentation/
injection_container.dart
main.dart
Repository Pattern
// Domain layer - abstract repository
abstract class UserRepository {
Future<Either<Failure, User>> getUser(String id);
Future<Either<Failure, void>> updateUser(User user);
}
// Data layer - implementation
class UserRepositoryImpl implements UserRepository {
final UserRemoteDataSource remoteDataSource;
final UserLocalDataSource localDataSource;
final NetworkInfo networkInfo;
UserRepositoryImpl({
required this.remoteDataSource,
required this.localDataSource,
required this.networkInfo,
});
Future<Either<Failure, User>> getUser(String id) async {
if (await networkInfo.isConnected) {
try {
final userModel = await remoteDataSource.getUser(id);
await localDataSource.cacheUser(userModel);
return Right(userModel.toEntity());
} on ServerException catch (e) {
return Left(ServerFailure(e.message));
}
} else {
try {
final cachedUser = await localDataSource.getCachedUser(id);
return Right(cachedUser.toEntity());
} on CacheException {
return Left(CacheFailure());
}
}
}
}
Use Cases
// Base use case
abstract class UseCase<Type, Params> {
Future<Either<Failure, Type>> call(Params params);
}
class NoParams extends Equatable {
List<Object?> get props => [];
}
// Concrete use case
class GetUser implements UseCase<User, GetUserParams> {
final UserRepository repository;
GetUser(this.repository);
Future<Either<Failure, User>> call(GetUserParams params) {
return repository.getUser(params.userId);
}
}
class GetUserParams extends Equatable {
final String userId;
const GetUserParams({required this.userId});
List<Object?> get props => [userId];
}
Dependency Injection with get_it
final sl = GetIt.instance;
Future<void> init() async {
// Features - Auth
// Bloc
sl.registerFactory(
() => AuthBloc(
loginUseCase: sl(),
logoutUseCase: sl(),
),
);
// Use cases
sl.registerLazySingleton(() => LoginUseCase(sl()));
sl.registerLazySingleton(() => LogoutUseCase(sl()));
// Repository
sl.registerLazySingleton<AuthRepository>(
() => AuthRepositoryImpl(
remoteDataSource: sl(),
localDataSource: sl(),
networkInfo: sl(),
),
);
// Data sources
sl.registerLazySingleton<AuthRemoteDataSource>(
() => AuthRemoteDataSourceImpl(client: sl()),
);
sl.registerLazySingleton<AuthLocalDataSource>(
() => AuthLocalDataSourceImpl(sharedPreferences: sl()),
);
// Core
sl.registerLazySingleton<NetworkInfo>(() => NetworkInfoImpl(sl()));
// External
final sharedPreferences = await SharedPreferences.getInstance();
sl.registerLazySingleton(() => sharedPreferences);
sl.registerLazySingleton(() => http.Client());
sl.registerLazySingleton(() => InternetConnectionChecker());
}
Anti-Patterns to Refactor
1. Unnecessary Containers
// BAD
Container(
child: Text('Hello'),
)
// GOOD
const Text('Hello')
// Only use Container when you need decoration, padding, constraints, etc.
2. Heavy Work in build()
// BAD: Expensive operation in build
Widget build(BuildContext context) {
final sortedItems = items..sort((a, b) => a.name.compareTo(b.name)); // Sorts every rebuild!
return ListView.builder(...);
}
// GOOD: Move to state or use selector
class _MyWidgetState extends State<MyWidget> {
late List<Item> _sortedItems;
void initState() {
super.initState();
_sortItem();
}
void didUpdateWidget(MyWidget oldWidget) {
super.didUpdateWidget(oldWidget);
if (widget.items != oldWidget.items) {
_sortItems();
}
}
void _sortItems() {
_sortedItems = List.of(widget.items)..sort((a, b) => a.name.compareTo(b.name));
}
}
3. Nested ScrollViews in Same Direction
// BAD: Nested scrollable in same direction
SingleChildScrollView(
child: Column(
children: [
ListView.builder(...), // Both scroll vertically!
],
),
)
// GOOD: Use shrinkWrap or CustomScrollView
CustomScrollView(
slivers: [
SliverToBoxAdapter(child: HeaderWidget()),
SliverList.builder(
itemBuilder: (context, index) => ItemWidget(items[index]),
),
],
)
// Or with shrinkWrap (use sparingly, has performance cost)
SingleChildScrollView(
child: Column(
children: [
ListView.builder(
shrinkWrap: true,
physics: const NeverScrollableScrollPhysics(),
...
),
],
),
)
4. Listener Lifecycle Issues
// BAD: Not disposing listeners
class _MyWidgetState extends State<MyWidget> {
void initState() {
super.initState();
stream.listen((data) => setState(() => _data = data));
}
}
// GOOD: Proper lifecycle management
class _MyWidgetState extends State<MyWidget> {
StreamSubscription? _subscription;
void initState() {
super.initState();
_subscription = stream.listen((data) => setState(() => _data = data));
}
void dispose() {
_subscription?.cancel();
super.dispose();
}
}
5. Improper GlobalKey Usage
// BAD: Creating GlobalKey in build
Widget build(BuildContext context) {
final formKey = GlobalKey<FormState>(); // New key every build!
return Form(key: formKey, ...);
}
// GOOD: Create GlobalKey as class member
class _MyFormState extends State<MyForm> {
final _formKey = GlobalKey<FormState>();
Widget build(BuildContext context) {
return Form(key: _formKey, ...);
}
}
6. StatelessWidget Functions vs Classes
// BAD: Function returns widget tree
Widget buildHeader() {
return Container(
child: Text('Header'),
);
}
// Usage
Column(
children: [
buildHeader(), // No widget identity, can't optimize
buildContent(),
],
)
// GOOD: Proper StatelessWidget
class Header extends StatelessWidget {
const Header({super.key});
Widget build(BuildContext context) {
return Container(
child: const Text('Header'),
);
}
}
Refactoring Process
Step 1: Analyze the Widget/Code
- Read the entire file and understand its purpose
- Identify responsibilities (UI, state, business logic, navigation)
- List all state variables and their dependencies
- Note any code smells or anti-patterns
- Check for missing const constructors
- Review Dart version features being used
Step 2: Plan the Refactoring
- Determine if widgets should be split
- Identify logic to extract to providers/blocs/services
- Plan Freezed models for data classes
- Consider Dart 3 features (patterns, records, sealed classes)
- Map out dependency injection needs
Step 3: Execute Incrementally
- Add const constructors where possible
- Extract reusable widgets
- Implement proper state management
- Create Freezed models for data
- Apply Dart 3 patterns and features
- Set up dependency injection
Step 4: Verify
- Run
flutter analyze- no warnings - Run
dart format .- consistent formatting - Test on device/emulator - UI works correctly
- Verify hot reload still works
- Check DevTools for unnecessary rebuilds
Output Format
When refactoring Flutter code, provide:
- Analysis Summary: Brief description of issues found
- Refactored Code: Complete, working code with improvements
- Changes Made: Bulleted list of specific changes
- Rationale: Brief explanation of why each change improves the code
- Additional Files: Any new files needed (models, providers, etc.)
Quality Standards
Code Quality Checklist
- Widgets follow Single Responsibility Principle
- const constructors used wherever possible
- Proper Keys for list items and stateful widgets
- BuildContext not used across async gaps
- State management follows chosen pattern consistently
- Freezed used for data models
- Dart 3 features applied where beneficial
- No heavy work in build methods
- Listeners properly disposed
Performance Checklist
- ListView.builder for long lists
- const widgets for static content
- No unnecessary Container widgets
- Images use caching (cached_network_image)
- Heavy computations moved out of build
- RepaintBoundary for complex static widgets
Architecture Checklist
- Clean separation of layers (presentation/domain/data)
- Dependency injection configured
- Repository pattern for data access
- Use cases for business logic
- Error handling with Either type or Result pattern
When to Stop Refactoring
Stop refactoring when:
- Widget is under 100 lines and has single responsibility
- State is properly managed with chosen pattern
- const constructors are applied throughout
- No obvious code smells remain
- flutter analyze shows no warnings
- Tests pass (if they exist)
- Performance is acceptable in DevTools
- Further changes would be premature optimization - don't optimize without profiling evidence
References
Related skills
More from snakeo/claude-debug-and-refactor-skills-plugin
refactor:nestjs
Refactor NestJS/TypeScript code to improve maintainability, readability, and adherence to best practices. Identifies and fixes circular dependencies, god object services, fat controllers with business logic, deep nesting, and SRP violations. Applies NestJS patterns including proper module organization, provider scopes, custom decorators, guards, interceptors, pipes, DTOs with class-validator, exception filters, CQRS, repository pattern, and event-driven architecture. Transforms code into exemplary implementations following SOLID principles.
42refactor:spring-boot
Refactor Spring Boot and Java code to improve maintainability, readability, and adherence to enterprise best practices. This skill transforms messy Spring Boot applications into clean, well-structured solutions following SOLID principles and Spring Boot 3.x conventions. It addresses fat controllers, improper transaction boundaries, field injection anti-patterns, and scattered configuration. Leverages Java 21+ features including record patterns, pattern matching for switch, virtual threads, and sequenced collections.
39debug:flutter
Debug Flutter applications systematically with this comprehensive troubleshooting skill. Covers RenderFlex overflow errors, setState() after dispose() issues, null check operator failures, platform channel problems, build context errors, and hot reload failures. Provides structured four-phase debugging methodology with Flutter DevTools, widget inspector, performance profiling, and platform-specific debugging for Android, iOS, and web targets.
38refactor:django
Refactor Django/Python code to improve maintainability, readability, and adherence to best practices. Transforms fat views, N+1 queries, and outdated patterns into clean, modern Django code. Applies Python 3.12+ features like type parameter syntax and @override decorator, Django 5+ patterns like GeneratedField and async views, service layer architecture, and PEP 8 conventions. Identifies and fixes anti-patterns including mutable defaults, bare exceptions, and improper ORM usage.
35refactor:nuxtjs
Refactor Nuxt.js/Vue code to improve maintainability, readability, and adherence to best practices. Identifies and fixes DRY violations, oversized components, deep nesting, SRP violations, data fetching anti-patterns with useFetch/useAsyncData/$fetch, poor composable organization, and mixed business/presentation logic. Applies Nuxt 3 patterns including auto-imports, proper data fetching, single-responsibility composables, TypeScript integration, runtime config, Nitro server routes, Nuxt Layers, middleware patterns, Pinia state management, and performance optimizations.
35refactor:laravel
Refactor PHP/Laravel code to improve maintainability, readability, and adherence to best practices. This skill transforms code using modern PHP 8.3+/8.4+ features like property hooks and typed constants, Laravel 11+ patterns including Actions and simplified structure, and SOLID principles. It addresses fat controllers, code duplication, N+1 queries, and missing type declarations. Apply when you notice business logic in controllers or legacy PHP patterns.
35