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