Comprehensive Flutter/Dart code quality tools including intelligent code review and automated formatting

version
2.2.0

Install

/plugin install flutter-tools@LucasXu0-flutter-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add LucasXu0/claude-code-plugin.

Contents

Discovered from source

Skills 2

Flutter Format

Expert knowledge about Flutter/Dart code formatting and analysis tools.

Core Tools

flutter analyze

Purpose: Static analysis to find errors, warnings, and lint suggestions

What it checks:

  • Syntax errors
  • Type errors
  • Unused imports and variables
  • Lint rules from analysis_options.yaml
  • Potential bugs and anti-patterns

When to use:

  • Before applying fixes (to identify issues)
  • After formatting (to verify no new issues)
  • As pre-commit validation

Output interpretation:

  • Errors: Must fix (compilation failures)
  • Warnings: Should fix (potential bugs)
  • Info: Optional improvements (style suggestions)

dart fix --apply

Purpose: Automatically fix lint issues and apply Dart language updates

What it fixes:

  • Deprecated API usage
  • Lint violations with automated fixes
  • Code modernization (e.g., null safety migration patterns)

When to use:

  • After flutter analyze identifies fixable issues
  • Before formatting (fixes may affect structure)
  • When migrating Dart versions

Safety considerations:

  • Safe: Lint fixes, deprecated API updates
  • Review needed: Major refactorings, null safety changes
  • Skip if: Syntax errors present, uncommitted important changes

Always show changes to user with git diff before proceeding.

dart format

Purpose: Consistent code formatting following Dart style guide

What it formats:

  • Indentation (2 spaces)
  • Line length (default 80 characters)
  • Bracket placement
  • Whitespace and newlines

What it doesn't change:

  • Code logic
  • Import order (use IDE or separate tool)
  • Comments content

When to use:

  • After code changes
  • After dart fix --apply
  • Before commits

Options:

  • . - Format entire project
  • lib test - Format specific directories
  • --line-length=120 - Custom line length (if needed)

Best Practices

Recommended Workflow

Standard sequence:

flutter analyze → dart fix --apply → dart format → flutter analyze

Why this order:

  1. Analyze first: Identify issues
  2. Fix: Auto-fix what's possible
  3. Format: Apply consistent style
  4. Re-analyze: Verify no new issues

Edge Cases

Generated Code

  • Files: *.g.dart, *.freezed.dart, *.gr.dart
  • Action: Exclude from formatting
  • Reason: Regenerated on build, formatting changes lost
  • How: Use dart format lib test instead of dart format .

Vendor/Third-Party Code

  • Directories: packages/, vendor/, .pub-cache/
  • Action: Don't format
  • Reason: Not your code, may break signatures
  • How: Target specific directories

Monorepos

  • Context: Multiple projects in one repository
  • Action: Format only relevant project
  • Reason: May affect other teams' code
  • How: cd project_name && dart format lib test

Build Runner Integration

  • When: Project uses build_runner for code generation
  • Action: Run build after fixing/formatting if generated files changed
  • Command: flutter pub run build_runner build --delete-conflicting-outputs

Syntax Errors

  • Issue: dart format fails on unparseable code
  • Action: Fix syntax errors first, then format
  • Detection: flutter analyze shows errors

Analysis Options

Custom Lint Rules (analysis_options.yaml)

  • Location: Project root
  • Purpose: Project-specific lint rules
  • Respect user's choices - don't suggest disabling their rules
  • Add exceptions only if user requests

Example:

linter:
  rules:
    prefer_const_constructors: true
    avoid_print: true

Output Reporting

What to show user:

  • Number of issues fixed by dart fix
  • Number of files formatted
  • Final analysis status (errors/warnings count)
  • List of modified files (or summary if >10)

Helpful next steps:

  • How to review changes: git diff
  • How to commit: git add . && git commit -m "chore: format code"

Error Handling

Common Failures

flutter analyze fails:

  • Cause: Not in Flutter project, SDK not installed, corrupt dependencies
  • Solution: Run flutter pub get to refresh dependencies

dart fix --apply fails:

  • Cause: Syntax errors, conflicting fixes
  • Solution: Fix syntax errors first, or skip and proceed with format only

dart format fails:

  • Cause: Syntax errors (rare)
  • Solution: Identify problematic file, fix syntax, or skip that file

Permission errors:

  • Cause: File permissions, read-only files
  • Solution: Check file permissions, may need user intervention

Integration Patterns

With Version Control

Pre-commit:

  • Format staged files: git diff --name-only --cached '*.dart' | xargs dart format
  • Verify: dart format --set-exit-if-changed . (fails if formatting needed)

In CI/CD:

  • Check formatting: dart format --set-exit-if-changed .
  • Run analysis: flutter analyze --no-fatal-warnings

With IDEs

Note: This skill complements IDE formatting by:

  • Ensuring all files formatted (IDE may only format open files)
  • Running full analysis workflow
  • Providing team-wide consistency

Decision Guidelines

When user says "format my code":

  • Run full workflow (analyze → fix → format → verify)
  • Default to formatting entire project
  • Exclude generated files automatically

When user says "just format, don't fix":

  • Skip dart fix --apply
  • Run only dart format
  • Still verify with flutter analyze after

When in doubt:

  • Ask user before applying risky fixes
  • Show changes before proceeding
  • Respect project's analysis_options.yaml

Quick Reference

# Full workflow
flutter analyze && dart fix --apply && dart format . && flutter analyze

# Format only (skip fixes)
dart format .

# Format specific directories
dart format lib test

# Exclude generated files
dart format lib --exclude '**.g.dart'

# Check formatting (CI/CD)
dart format --set-exit-if-changed .

# Custom line length
dart format --line-length=120 .

Key Principles

  1. Analyze before and after - Catch issues early and verify fixes
  2. Show changes - User should review before committing
  3. Respect configuration - Use project's analysis_options.yaml
  4. Handle edge cases - Generated code, vendor code, monorepos
  5. Report clearly - Summarize what changed and next steps

Flutter Code Review

This skill is directly invocable. See workflow.md for the complete 5-step execution strategy.

Expert knowledge for identifying critical bugs, anti-patterns, and code quality issues in Flutter/Dart code.

Execution Instructions

When invoked directly (e.g., via /flutter-review command):

  1. Follow the 5-step workflow in workflow.md
  2. Apply the priority-based checks defined below
  3. Generate a comprehensive review report
  4. Offer to automatically fix issues found

Priority-Based Analysis

P0 - Critical (Must Fix Before Merge)

Issues that cause crashes, data loss, security vulnerabilities, or visual bugs.

Null Safety Violations

Force Unwrap Without Checks (variable!, expression!.property)

  • Risk: Runtime crash with "Null check operator used on a null value"
  • Fix: Extract nullable values to local variables, check for null, then use non-null variable
  • Preferred Pattern: Extract property to local variable → check null → use promoted non-null variable
  • Avoid: Checking widget.property == null then using widget.property with ! operator
  • → Details: reference.md#avoid_non_null_assertion

Unsafe Nullable Access

  • Risk: Null pointer exceptions when accessing properties without checks
  • Fix: Add null checks before property access
  • → Details: reference.md#missing_null_safety

Unsafe Type Casts (value as Type)

  • Risk: Type cast errors at runtime
  • Fix: Use pattern matching or check with is operator first
  • → Details: reference.md#unsafe_type_casts
Flutter Lifecycle Issues

setState Without Mounted Check

  • Risk: setState() called after dispose() crashes app
  • Fix: Add if (!mounted) return; before setState in async callbacks
  • → Details: reference.md#avoid_mounted_in_setstate

State Modifications After Disposal

  • Risk: Memory leaks and unexpected behavior
  • Fix: Check mounted or cancel operations in dispose
  • → Details: reference.md#state_after_disposal
Memory Leaks

Resources That Must Be Disposed: TextEditingController, AnimationController, ScrollController, TabController, PageController, FocusNode, StreamSubscription, Timer, any class with addListener() called

Detection: Check if controllers/subscriptions created in fields or initState have corresponding dispose() calls. Verify ALL resources disposed, not just presence of dispose method.

  • → Details: reference.md#dispose_class_fields
Logic Errors

Incorrect Conditional Logic

  • || vs && confusion, missing null checks in compounds, negation errors
  • → Details: reference.md#logic_errors_conditionals

Missing Error Handling

  • API calls, file operations, JSON parsing without try-catch
  • → Details: reference.md#missing_error_handling

Infinite Loops

  • Loops without termination or where condition never changes
  • → Details: reference.md#infinite_loops

Race Conditions

  • Multiple async operations modifying same state without guards
  • → Details: reference.md#race_conditions
Bloc State Synchronization Issues

Only check when flutter_bloc or bloc in dependencies.

BlocListener/BlocConsumer Missing Initial State

  • Risk: Widget state (TextEditingController, variables) not initialized from bloc's initial state
  • Problem: Listener callbacks only fire on state changes, not initial state. If bloc emits state before widget creation, initial state is missed
  • Fix: Initialize widget state in initState() from current bloc state, AND have listener for updates
  • → Details: reference.md#bloc_missing_initial_state
Text Overflow in Flex Layouts

Text Without Constraints in Row/Column

  • Risk: RenderFlex overflow errors, visual bugs, unusable UI
  • Fix: Wrap Text in Flexible/Expanded widget AND/OR add overflow handling (TextOverflow.ellipsis)
  • → Details: reference.md#text_overflow_flex

P1 - Important (Should Fix)

Issues causing logic bugs and maintainability problems.

Collection Equality

Using == on Collections (list1 == list2, map1 == map2)

  • Problem: Dart uses reference equality, always false for different instances
  • Fix: Use package:collection - ListEquality().equals(), MapEquality().equals(), or DeepCollectionEquality().equals()
  • Exception: const collections (same instance)
  • → Details: reference.md#avoid_collection_equality_checks
Code Complexity

Deep Nesting (>4 levels)

  • Problem: Reduces readability, increases cognitive load
  • Fix: Extract methods, use early returns, guard clauses
  • → Details: reference.md#deep_nesting

Long Methods (>100 lines)

  • Problem: Violates Single Responsibility Principle
  • Fix: Break into smaller focused methods
  • → Details: reference.md#long_methods

Long Build Methods (>50 lines)

  • Problem: Too much UI logic in build method, hard to maintain
  • Fix: Extract to buildWidget helpers (buildHeader, buildBody) or create separate widget files
  • → Details: reference.md#long_build_methods
Widget Organization

Multiple Widget Definitions Per File

  • Problem: Reduces code organization, testability, and reusability
  • Fix: Each widget class must be in its own file (e.g., UserCard in user_card.dart)
  • No exceptions: Even private (_Widget) or small helper widgets should be extracted
  • → Details: reference.md#multiple_widgets_per_file
Late Modifier Usage

Avoid Late Keyword

  • Risk: Defers initialization to runtime, can cause LateInitializationError
  • Fix: Initialize in constructor, use nullable types, or required parameters
  • Exception: DI frameworks with guaranteed initialization
  • → Details: reference.md#avoid_late_keyword
Bloc Anti-Patterns

Only check when flutter_bloc or bloc in dependencies.

Public Fields in BLoC

  • Problem: Breaks encapsulation, allows external state modification
  • Fix: Make fields private, expose through state
  • → Details: reference.md#bloc_public_fields

Public Methods in BLoC

  • Problem: BLoCs should only respond to events
  • Fix: Create events and use add() instead
  • → Details: reference.md#bloc_public_methods

Mutable Events

  • Problem: Events should be immutable data
  • Fix: Add @immutable, make fields final, use const constructors
  • → Details: reference.md#bloc_mutable_events

Non-Sealed States

  • Problem: Can't exhaustively pattern match
  • Fix: Use sealed class for state base, final class for implementations
  • → Details: reference.md#bloc_non_sealed_states
Provider Anti-Patterns

Only check when provider in dependencies.

context.read() in Build

  • Problem: Won't rebuild when provider changes
  • Fix: Use context.watch() for reactive data
  • → Details: reference.md#provider_read_in_build

Old Provider Syntax (Provider.of(context, listen: true))

  • Problem: Outdated, less readable
  • Fix: Use context.watch() or context.read()
  • → Details: reference.md#provider_old_syntax

Missing Disposal in ChangeNotifier

  • Problem: Memory leaks from undisposed resources
  • Fix: Override dispose() and clean up all resources
  • → Details: reference.md#provider_missing_disposal
Logic Issues

Incorrect Operators

  • Using = instead of == in conditions, comparing incompatible types
  • → Details: reference.md#incorrect_operators

Missing Edge Cases

  • No empty collection checks before .first/.last, no bounds checking
  • → Details: reference.md#missing_edge_cases

Off-By-One Errors

  • Loop conditions with <= instead of < for length
  • → Details: reference.md#off_by_one_errors

P2 - Code Quality (Nice to Have)

Improvements for maintainability.

Magic Numbers

Hardcoded Numbers Without Context

  • Exceptions: 0, 1, -1, obvious widget dimensions (padding: 16)
  • Fix: Define as named constants
  • → Details: reference.md#magic_numbers
TODO/FIXME Comments

Markers for Incomplete Work

  • Patterns: // TODO:, // FIXME:, // HACK:
  • Action: Track and address before merge
  • → Details: reference.md#todo_comments
Function Ordering

Private Functions After Public Functions

  • Problem: Private functions placed before public ones reduces readability and makes it harder to understand the public API
  • Fix: Move all private methods (starting with _) after public methods
  • Widget-specific order: initState → other lifecycle methods → dispose → build → public methods → private methods
  • → Details: reference.md#function_ordering
Long Classes (>500 lines)

Classes Exceeding 500 Lines

  • Problem: Violates Single Responsibility, may contain dead code
  • Fix: Split into multiple classes, extract to mixins/utilities
  • Action: Review for unused methods, commented code, duplicate logic
  • → Details: reference.md#long_classes
Moderate Nesting (3-4 levels)

Nesting Depth 3-4

  • Consider simplification for readability
  • → Details: reference.md#moderate_nesting

Dependency-Specific Knowledge

Bloc Pattern Detection

Trigger: flutter_bloc or bloc in pubspec.yaml

Key Principles:

  • State is immutable and sealed
  • Events are immutable
  • No public methods (only event handlers)
  • No public fields (only private state)
  • UI never contains business logic

→ See reference.md#bloc_pattern for state/event patterns

Provider Pattern Detection

Trigger: provider in pubspec.yaml

Key Principles:

  • Use context.watch() for reactive rebuilds
  • Use context.read() only for one-time reads (not in build)
  • Use context.select() for performance optimization
  • Always dispose resources in ChangeNotifier

→ See reference.md#provider_pattern for usage patterns


Context Awareness

When NOT to Flag

Test Files:

  • More lenient with force unwraps in test setup
  • Focus on logic errors, not style

Generated Code:

  • Files matching _.g.dart, _.freezed.dart, *.gr.dart
  • Skip entirely - will be regenerated

Intentional Patterns:

  • Type check before cast (e.g., if (x is String) { x.length; })
  • Controlled environments after validation (e.g., validated user input)

Note: Even with null check immediately before force unwrap, prefer extracting to local variable for type promotion instead of using the ! operator.

When TO Flag Even If...

Pattern is common:

  • Common doesn't mean correct
  • Flag reference equality on collections even if widespread

"It works":

  • Working code can still have bugs
  • Flag potential issues even if not currently crashing

Dispose exists but incomplete:

  • If new controllers added but not in dispose
  • Check ALL resources, not just presence of dispose method

Widget is private or small:

  • Flag ALL widget definitions in same file (except StatefulWidget's State class)
  • Private (_Widget) does not exempt from one-widget-per-file rule
  • "Small" size does not exempt from one-widget-per-file rule
  • Every widget class deserves its own file for testability and organization

Review Output Format

Report Structure

Summary:

  • Count by priority (P0: X, P1: Y, P2: Z)
  • Clear status (Pass / Must Fix / Recommended)
  • Overall recommendation (🔴 BLOCK / 🟡 REVIEW NEEDED / 🟢 APPROVED)

Issue Format:

  • File path:line_number
  • Issue type and priority
  • Problem explanation
  • Current code snippet (with context)
  • Fixed code snippet
  • Benefit of fix

Organization:

  • P0 first (most critical)
  • Within priority, group by type
  • Use tables for many similar issues (>3)
  • Detailed format for complex issues

Recommendation Guidelines

🔴 BLOCK - Any P0 issues present (must fix before merge) 🟡 REVIEW NEEDED - No P0, but P1 issues present (should fix) 🟢 APPROVED - No P0 or P1, only P2 optional improvements


Analysis Efficiency

Focus on Changed Code:

  • Analyze additions and modifications (+ in diff)
  • Use surrounding context from diff
  • Don't review entire codebase

Selective Deep Dives: Read full files only when:

  • Diff context insufficient
  • Need to verify disposal (new controllers/streams added)
  • Need class structure or imports

File Type Guides Analysis:

  • Widgets: Lifecycle, mounted, dispose
  • BLoCs: Encapsulation, events, states
  • Providers: Disposal, context usage
  • Models: Immutability, equality
  • Services: Error handling, async patterns

Key Principles

  1. Safety First - P0 issues can crash apps, prioritize these
  2. Be Specific - Always provide file:line, code snippets, fixes
  3. Avoid False Positives - When uncertain, don't flag or mark P2
  4. Context Matters - Understand intent before flagging
  5. Actionable Feedback - Every issue needs clear, copy-paste ready fix
  6. Respect Patterns - Understand project architecture before suggesting changes

Additional Resources

For detailed explanations of each check, see reference.md.

For code examples showing good vs bad patterns, see examples.md.

Commands 2

Flutter Format Command

IMPORTANT: You MUST use the flutter-format skill for this task.

Apply the flutter-format skill to run automated Flutter/Dart code formatting and cleanup workflow.

The skill contains all the instructions for the complete workflow.

Flutter Code Review Command

IMPORTANT: You MUST use the flutter-review skill for this task.

Apply the flutter-review skill to perform comprehensive Flutter/Dart code review with priority-based analysis.

The skill contains:

  • Priority-based check definitions (P0/P1/P2)
  • 6-step execution workflow
  • Detailed explanations and code examples

Follow the workflow in skills/flutter-review/workflow.md to execute the review.

Agents 1

You are an elite Flutter/Dart code reviewer with deep expertise in mobile application development, Flutter framework internals, Dart language best practices, and modern app architecture patterns. Your mission is to provide thorough, constructive code reviews that elevate code quality while teaching developers Flutter best practices.

Flutter Review Skill

The flutter-review skill is automatically loaded and provides:

  • Priority-based check definitions (P0/P1/P2) in SKILL.md
  • 5-step execution workflow in workflow.md
  • Detailed reference documentation in reference.md
  • Comprehensive code examples in examples.md

Follow the workflow from the skill to conduct systematic code reviews.

Your Responsibilities

  1. Execute the workflow from the flutter-review skill step-by-step
  2. Apply priority-based checks (P0 → P1 → P2) to identify issues
  3. Generate comprehensive reports with clear recommendations
  4. Interact with users to clarify requirements and offer automated fixes
  5. Provide educational feedback explaining the "why" behind each issue

Key Principles

  • Efficiency First: Use git diff analysis and selective file reading (see workflow.md Step 3)
  • Priority-Driven: Focus on P0 issues first, then P1, then P2
  • Context-Aware: Understand file types (Widget, BLoC, Provider, Service) to apply relevant checks
  • Dependency-Smart: Enable Bloc/Provider checks only when dependencies detected
  • Actionable Feedback: Every issue needs file:line, problem, current code, fixed code, and benefit
  • Educational: Explain the "why" behind each issue using reference.md

Output Format (from workflow.md Step 5)

Save results to /tmp/flutter_review/{timestamp}-{repo}-{branch}-{id}.md with:

  • Summary table (P0/P1/P2 counts and status)
  • Recommendation (🔴 BLOCK / 🟡 REVIEW NEEDED / 🟢 APPROVED)
  • Issues organized by priority with file:line references
  • Clear next steps
  • Offer to fix issues automatically if P0 or P1 exist

Critical Reminders

  • ALWAYS follow workflow.md - don't skip steps
  • Check ALL resources for disposal - controllers, streams, subscriptions, timers
  • Verify mounted before setState in async callbacks
  • Flag force unwrap (!) unless after explicit type check
  • Use the recommendation guidelines from workflow.md to determine 🔴/🟡/🟢
  • Ask user if they want fixes when P0 or P1 issues found

Self-Check Before Finalizing

  • Did I follow the 5-step workflow from workflow.md?
  • Did I apply checks from SKILL.md based on priority?
  • Are all issues documented with file:line, code snippets, and fixes?
  • Did I use the correct output format from workflow.md?
  • Did I offer to fix issues automatically?
  • Is my recommendation (🔴/🟡/🟢) correct per guidelines?

Your goal is to leverage the comprehensive flutter-review skill to catch critical bugs, enforce best practices, and help developers write production-ready Flutter code.

Sponsors

Details

Marketplace
LucasXu0/claude-code-plugin
Source
plugins/flutter-tools
Author
Lucas Xu
Category
Developer Tools

More from LucasXu0/claude-code-plugin

All 2