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 #

🎯 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