Flutter UI Guard 🛡️

Flutter UI Guard is a powerful static analysis tool for Flutter developers that helps identify performance issues, best practice violations, and optimization opportunities in your widget tree before they impact your app's performance.

---

✨ Features

🎯 Core Analysis

• Const Detection - Identifies widgets that should be marked as const for better performance
• Deep Nesting Analysis - Warns about excessive widget tree depth that can hurt readability and performance
• Heavy Build Detection - Finds widgets with too many children that should use builders
• Container Optimization - Suggests using SizedBox instead of empty Container widgets
• Opacity Performance - Warns about expensive Opacity widgets and suggests alternatives

🚀 Performance Checks

• ListView Optimization - Detects missing itemExtent or prototypeItem for better scrolling
• GestureDetector vs InkWell - Suggests Material Design alternatives for better UX
• MediaQuery Usage - Helps identify potential rebuild issues with MediaQuery
• Column to ListView - Suggests ListView.builder for long scrollable lists

📊 Detailed Reporting

• Severity Levels - Info, Warning, Error, and Critical classifications
• Actionable Suggestions - Every issue comes with a concrete fix suggestion
• Performance Metrics - Analysis time, widget count, and max depth tracking
• Beautiful Console Output - Color-coded, emoji-rich reports

---

📦 Installation

Add this to your pubspec.yaml:

dev_dependencies:
  flutter_ui_guard: ^0.0.3

Then run:

flutter pub get

---

🚀 Quick Start

Basic Usage

import 'package:flutter/material.dart';
import 'package:flutter_guard/flutter_ui_guard.dart';

void main() {
  final widget = Scaffold(
    appBar: AppBar(
      title: Text('My App'), // ⚠️ Should be const
    ),
    body: Column(
      children: [
        Text('Hello World'), // ⚠️ Should be const
        const Text('This is optimized'), // ✅ Good!
      ],
    ),
  );

  // Analyze the widget tree
  final report = FlutterGuard.analyze(rootWidget: widget);
  
  // Print detailed report
  report.printReport();
}

Custom Configuration

final report = FlutterGuard.analyze(
  rootWidget: myWidget,
  config: GuardConfig(
    maxNestingLevel: 5,        // Stricter nesting limit
    maxChildrenWarning: 3,     // Warn with fewer children
    checkConst: true,          // Enable const checking
    checkNesting: true,        // Enable nesting checks
    checkHeavyBuilds: true,    // Enable heavy build detection
    checkListView: true,       // Enable ListView optimization
    checkOpacity: true,        // Enable Opacity warnings
    checkContainer: true,      // Enable Container optimization
    verbose: false,            // Disable verbose logging
  ),
);

report.printReport();

---

📖 Examples

Example 1: Performance Issues

Before:

Column(
  children: List.generate(
    100,
    (i) => Text('Item $i'), // ❌ Heavy build!
  ),
)

After (Following Flutter Guard Suggestion):

ListView.builder(
  itemCount: 100,
  itemBuilder: (context, i) => Text('Item $i'), // ✅ Optimized!
)

Example 2: Const Optimization

Before:

Text('Hello World') // ⚠️ Not const

After:

const Text('Hello World') // ✅ Const widget - better performance!

Example 3: Container vs SizedBox

Before:

Container(
  width: 16,
  height: 16,
) // ℹ️ Empty container

After:

const SizedBox(
  width: 16,
  height: 16,
) // ✅ More efficient spacing

---

📊 Report Output

============================================================
🛡️  FLUTTER GUARD ANALYSIS REPORT
============================================================
📊 Total Widgets Analyzed: 45
📏 Max Nesting Depth: 8
⏱️  Analysis Time: 12ms
────────────────────────────────────────────────────────────
📋 Issues Found: 7
   ℹ️  Info: 3
   ⚠️  Warnings: 3
   ❌ Errors: 1
   🔴 Critical: 0
============================================================

📝 Detailed Issues:

⚠️ [Text] Text widget should be const when data is static
   💡 Add const: const Text("your text")

🔴 [Container] Container has both color and decoration
   💡 Use decoration: BoxDecoration(color: yourColor) instead

ℹ️ [GestureDetector] GestureDetector detected
   💡 Consider using InkWell for Material Design ripple effects

============================================================

---

🎛️ Configuration Options

Option	Type	Default	Description
maxNestingLevel	int	6	Maximum widget nesting depth before warning
maxChildrenWarning	int	5	Max children before suggesting builder pattern
checkConst	bool	true	Enable const usage detection
checkNesting	bool	true	Enable deep nesting warnings
checkHeavyBuilds	bool	true	Enable heavy build detection
checkMediaQuery	bool	true	Enable MediaQuery usage checks
checkListView	bool	true	Enable ListView optimization checks
checkGestureDetector	bool	true	Enable GestureDetector vs InkWell suggestions
checkOpacity	bool	true	Enable Opacity performance warnings
checkContainer	bool	true	Enable Container optimization suggestions
verbose	bool	false	Enable verbose widget tree logging

---

🎯 Best Practices Checked

✅ DO:

• Use const constructors whenever possible
• Use ListView.builder() for long lists
• Use SizedBox for spacing instead of empty Container
• Use InkWell for Material Design tap effects
• Add itemExtent or prototypeItem to ListView when possible
• Keep widget tree nesting under 6-7 levels

❌ DON'T:

• Forget const on static widgets
• Use Column with 50+ children
• Use empty Container for spacing
• Nest widgets more than 7-8 levels deep
• Set both color and decoration on Container
• Use Opacity when AnimatedOpacity would work

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

git clone https://github.com/smtechviral/flutter_ui_guard.git
cd flutter_ui_guard
flutter pub get
flutter test

---

📝 Changelog

See CHANGELOG.md for a detailed list of changes.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Inspired by Flutter's performance best practices
• Built with ❤️ for the Flutter community

---

📞 Support

• 🐛 Report Bug
• 💡 Request Feature
• 📧 Contact: [email protected]

---

⭐ Show Your Support

If you found this package helpful, please give it a ⭐ on GitHub!

---

Made with ❤️ by the Flutter community