network_inspector_pro 0.1.0

Professional Flutter network debugging with a revolutionary single-class API. Beautiful UI, real-time monitoring, zero configuration. Only one public class - all implementation stays private.

🚀 Flutter Network Inspector

A beautiful, plug-and-play network request inspector for Flutter development. Monitor HTTP requests, responses, timing, and debug APIs with an intuitive UI and zero configuration.

✨ Features

🎯 Single Public API

• One class to rule them all - FlutterNetworkInspector is the only public API
• Zero implementation exposure - All internal details are completely hidden
• Clean, minimal interface - Simple methods, no complexity

🎨 Beautiful UI

• Clean, intuitive Material Design interface

• Color-coded status indicators

  • 🟢 Success
  • 🔴 Error
  • 🟠 Redirect
  • ⚪ Pending

• Expandable request details with 4-tab view

• Real-time updates as requests happen

📊 Comprehensive Monitoring

• 📡 Request Details: URL, method, headers, body
• 📨 Response Data: Status code, headers, formatted JSON body
• ⚡ Performance Metrics: Request duration, timing breakdown
• 🔍 Search & Filter: Find specific requests instantly
• 📈 Statistics: Success rates, error counts, average response times

🚀 Developer Experience

• 📱 Floating Overlay: Draggable button for easy access
• 🔧 Debug-Only Mode: Automatically disabled in release builds
• 💾 Memory Efficient: Keeps only recent 500 requests
• 🎛️ Customizable: Configure colors, position, and behavior

🚀 Quick Start (2 Steps)

1. Installation

Add to your pubspec.yaml:

dependencies:
  flutter_network_inspector: ^0.1.0
  dio: ^5.4.0  # Required for HTTP interception

2. Setup (2 Lines of Code)

import 'package:flutter/material.dart';
import 'package:dio/dio.dart';
import 'package:flutter_network_inspector/flutter_network_inspector.dart';

void main() {
  // Step 1: Add interceptor to your Dio client
  final dio = Dio();
  dio.interceptors.add(FlutterNetworkInspector.dioInterceptor);
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // Step 2: Wrap your app with the network inspector
    return FlutterNetworkInspector.wrapApp(
      MaterialApp(
        title: 'My App',
        home: MyHomePage(),
      ),
    );
  }
}

That's it! 🎉 Tap the floating purple button to view all network requests.

📖 Complete API Reference

Core Methods

class FlutterNetworkInspector {
  // Step 1: Add to your Dio client
  static Interceptor get dioInterceptor;
  
  // Step 2: Wrap your app
  static Widget wrapApp(Widget child, {
    bool? enabled,                              // Default: debug mode only
    NetworkInspectorPosition position,          // Default: bottom-right
  });
  
  // Statistics and management
  static NetworkInspectorStatistics getStatistics();
  static void clearAllRequests();
  static void enable();
  static void disable();
  static bool get isEnabled;
  static int get totalRequests;
}

Position Options

enum NetworkInspectorPosition {
  topLeft, topRight, bottomLeft, bottomRight, centerLeft, centerRight
}

Statistics

class NetworkInspectorStatistics {
  int get totalRequests;           // Total number of requests
  int get successfulRequests;      // Successful requests (2xx)
  int get failedRequests;          // Failed requests (4xx/5xx)
  double get successRate;          // Success percentage (0-100)
  double get averageResponseTime;  // Average response time (ms)
  int get fastestRequest;          // Fastest request time (ms)
  int get slowestRequest;          // Slowest request time (ms)
}

🎯 Usage Examples

Basic Usage

// Setup (once in main.dart)
final dio = Dio();
dio.interceptors.add(FlutterNetworkInspector.dioInterceptor);

// Wrap your app
FlutterNetworkInspector.wrapApp(
  MaterialApp(home: MyPage()),
)

// Make requests normally - they're automatically captured!
final response = await dio.get('https://api.example.com/users');

Custom Configuration

FlutterNetworkInspector.wrapApp(
  MaterialApp(home: MyPage()),
  enabled: kDebugMode,                    // Only in debug builds
  position: NetworkInspectorPosition.topRight,  // Top-right corner
)

Access Statistics

final stats = FlutterNetworkInspector.getStatistics();
print('Success rate: ${stats.successRate}%');
print('Average response time: ${stats.averageResponseTime}ms');
print('Total requests: ${stats.totalRequests}');

Management

// Check status
if (FlutterNetworkInspector.isEnabled) {
  print('Inspector is capturing requests');
}

// Clear all captured requests
FlutterNetworkInspector.clearAllRequests();

// Temporarily disable
FlutterNetworkInspector.disable();
// ... make some requests that won't be captured ...
FlutterNetworkInspector.enable();

🎨 UI Features

Main List View

• Color-coded requests for instant status recognition
• Search bar to filter by URL, method, or status
• Expandable cards showing request summary
• Real-time updates as new requests arrive

Detailed Request View (4 Tabs)

1. Overview: Status, method, URL, timing summary
2. Request: Headers, body, query parameters
3. Response: Status code, headers, formatted JSON
4. Timing: Detailed performance breakdown

Floating Button

• Draggable - reposition anywhere on screen
• Live badge showing request count
• Error indicator - red dot for failed requests
• Tap to open full inspector interface

🔧 Advanced Features

Position Customization

// All available positions
FlutterNetworkInspector.wrapApp(
  myApp,
  position: NetworkInspectorPosition.topLeft,     // Top-left
  position: NetworkInspectorPosition.topRight,    // Top-right  
  position: NetworkInspectorPosition.bottomLeft,  // Bottom-left
  position: NetworkInspectorPosition.bottomRight, // Bottom-right (default)
  position: NetworkInspectorPosition.centerLeft,  // Center-left
  position: NetworkInspectorPosition.centerRight, // Center-right
)

Conditional Enabling

FlutterNetworkInspector.wrapApp(
  myApp,
  enabled: kDebugMode && debugMode,    // Custom conditions
  enabled: !kReleaseMode,              // All non-release builds
  enabled: Platform.isIOS,             // Platform-specific
)

Statistics Dashboard

void showNetworkStats(BuildContext context) {
  final stats = FlutterNetworkInspector.getStatistics();
  
  showDialog(
    context: context,
    builder: (context) => AlertDialog(
      title: Text('Network Statistics'),
      content: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Text('Total Requests: ${stats.totalRequests}'),
          Text('Success Rate: ${stats.successRate.toStringAsFixed(1)}%'),
          Text('Avg Response: ${stats.averageResponseTime.toStringAsFixed(1)}ms'),
          Text('Fastest: ${stats.fastestRequest}ms'),
          Text('Slowest: ${stats.slowestRequest}ms'),
        ],
      ),
    ),
  );
}

🎨 Screenshots

Floating Button	Request List	Request Details	Search & Filter
[Button]	[List]	[Details]	[Search]

🔥 Why This Package?

vs. Other Solutions

• Simpler: One class vs. multiple components to configure
• Cleaner: No implementation details exposed
• Safer: Private internals mean no breaking changes
• Beautiful: Modern Material Design 3 UI
• Powerful: Complete feature set with statistics

vs. Manual Logging

• Visual: Beautiful UI vs. console logs
• Interactive: Tap to explore vs. static text
• Organized: Structured data vs. scattered logs
• Persistent: View anytime vs. lost in console
• Rich: JSON formatting, timing, search vs. basic text

⚡ Performance

• Zero Impact: No effect on your app's network performance
• Memory Efficient: Automatically manages memory with LRU cache (500 requests)
• Async Processing: All UI updates happen asynchronously
• Debug Only: Automatically disabled in release builds (when enabled: kDebugMode)

🏗️ Architecture

The package uses a single public API design pattern:

┌─────────────────────────────────┐
│   FlutterNetworkInspector       │  ← ONLY public class
│   (Your clean API)              │
├─────────────────────────────────┤
│   Internal Implementation       │  ← All private & hidden
│   • NetworkInspector            │
│   • NetworkRequest              │
│   • DioInterceptor              │
│   • InspectorOverlay            │
│   • InspectorScreen             │
│   • All UI Components           │
└─────────────────────────────────┘

Benefits:

• ✅ Simple: Only one class to learn
• ✅ Future-proof: Internal changes won't break your code
• ✅ Professional: Follows Flutter/Dart best practices
• ✅ Clean docs: Only meaningful APIs are documented

🛠️ Development

Run Example

git clone https://github.com/yourusername/flutter_network_inspector.git
cd flutter_network_inspector/example
flutter run

Run Tests

flutter test
# All tests pass - only public API is tested

Generate Documentation

make docs           # Generate API documentation
make serve-docs     # Generate and serve locally

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/yourusername/flutter_network_inspector.git
cd flutter_network_inspector

# Install dependencies
make install

# Run tests
make test

# Generate docs
make docs

📝 License

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

🙏 Acknowledgments

• Inspired by Chucker for Android
• Built with ❤️ for the Flutter community
• Special thanks to all contributors

📞 Support

• 📚 Documentation
• 🐛 Bug Reports
• 💬 Discussions
• 📧 Email: [e-mail]

---

Made with ❤️ by Your Name

⭐ Star this repo if it helped you!

📋 Detailed Usage

Advanced Configuration

Custom Overlay Position

MaterialApp(
  home: MyHomePage(),
).withNetworkInspector(
  enabled: kDebugMode,              // Only show in debug builds
  position: Alignment.topRight,     // Position in top-right corner
);

Manual Overlay Setup

InspectorOverlay(
  enabled: !kReleaseMode,
  position: Alignment.bottomLeft,
  child: MaterialApp(
    home: MyHomePage(),
  ),
)

Programmatic Access

import 'package:flutter_network_inspector/flutter_network_inspector.dart';

// Access the inspector singleton
final inspector = NetworkInspector.instance;

// Get all captured requests
List<NetworkRequest> requests = inspector.requests;

// Search for specific requests
inspector.setSearchQuery('api/users');

// Filter by status
inspector.setStatusFilter(RequestStatus.error);

// Get statistics
Map<String, dynamic> stats = inspector.getStatistics();
print('Success rate: ${stats['successRate']}%');
print('Average response time: ${stats['averageResponseTime']}ms');

// Clear all requests
inspector.clearAll();

Custom UI Integration

Standalone Inspector Screen

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => const InspectorScreen(),
  ),
);

Inspector in Bottom Sheet

showModalBottomSheet(
  context: context,
  builder: (context) => SizedBox(
    height: MediaQuery.of(context).size.height * 0.8,
    child: const InspectorScreen(),
  ),
);

📊 Screenshots

Main List View	Request Details	Response Body	Search & Filter
[List]	[Details]	[Response]	[Search]

🎨 Color Coding

The Network Inspector uses intuitive color coding for instant status recognition:

• 🟢 Green (2xx): Successful requests
• 🔴 Red (4xx/5xx): Client/server errors
• 🟠 Orange (3xx): Redirects
• ⚪ Gray: Pending requests

⚡ Performance

• Zero Impact: No effect on your app's network performance
• Memory Efficient: Automatically manages memory with LRU cache (500 requests)
• Async Processing: All UI updates happen asynchronously
• Debug Only: Automatically disabled in release builds

🔧 Advanced Features

Request Statistics

final stats = NetworkInspector.instance.getStatistics();
/*
{
  'totalRequests': 42,
  'successfulRequests': 38,
  'failedRequests': 4,
  'successRate': 90.5,
  'averageResponseTime': 245.7,
  'fastestRequest': 123,
  'slowestRequest': 1205
}
*/

Custom Request Filtering

// Filter by multiple criteria
inspector.setSearchQuery('POST'); // Find all POST requests
inspector.setStatusFilter(RequestStatus.error); // Show only errors

// Programmatic filtering
final errorRequests = inspector.requests
    .where((req) => req.status == RequestStatus.error)
    .toList();

Export Data

// Get all requests as JSON
final requestsJson = inspector.requests
    .map((req) => req.toJson())
    .toList();

// Save to file or send to analytics
await saveNetworkLogs(requestsJson);

🛠️ API Reference

Core Classes

NetworkInspector

The main singleton class that manages request storage and filtering.

Key Methods:

• instance - Get the singleton instance
• requests - Get filtered list of requests
• setSearchQuery(String) - Filter requests by search term
• setStatusFilter(RequestStatus) - Filter by request status
• clearAll() - Clear all stored requests
• getStatistics() - Get performance statistics

NetworkInspectorDioInterceptor

Dio interceptor that automatically captures requests and responses.

final dio = Dio();
dio.interceptors.add(NetworkInspectorDioInterceptor());

InspectorScreen

Main UI widget for displaying network requests.

InspectorOverlay

Floating overlay widget with draggable button.

NetworkRequest

Data model representing a complete HTTP request/response cycle.

Key Properties:

• url, method, headers, requestBody
• responseCode, responseHeaders, responseBody
• status, duration, requestTime, responseTime
• prettyResponseBody - Formatted JSON response
• isSuccess, isError, isPending - Status helpers

Extension Methods

Widget.withNetworkInspector()

Convenient method to add network monitoring to any widget.

MaterialApp(home: MyPage()).withNetworkInspector(
  enabled: kDebugMode,
  position: Alignment.topRight,
);

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/yourusername/flutter_network_inspector.git
cd flutter_network_inspector

# Install dependencies
flutter pub get

# Run tests
flutter test

# Run example app
cd example
flutter run

📝 License

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

🙏 Acknowledgments

• Inspired by Chucker for Android
• Built with ❤️ for the Flutter community
• Special thanks to all contributors

📞 Support

• 📚 Documentation
• 🐛 Bug Reports
• 💬 Discussions
• 📧 Email: [e-mail]

---

Made with ❤️ by Your Name

⭐ Star this repo if it helped you!

✨ Features

• 🔍 Beautiful UI: Clean, expandable list view with color-coded status indicators
• 🔌 Plug & Play: Minimal setup - just add one line of code
• 📊 Comprehensive Logging: URL, method, headers, request/response body, timing
• 🎯 Multiple HTTP Clients: Works with Dio, HTTP package, and any HttpClient
• 🔍 Search & Filter: Find specific requests quickly
• 📱 Overlay Widget: Floating button for easy access during development
• 💾 Export Options: Copy URLs and request details
• 🎨 Color Coding: Visual status indicators (green=success, red=error, orange=pending)
• ⚡ Performance Metrics: Response time analysis and request statistics
• 🔧 Development Only: Easy to enable/disable for different build modes

🚀 Quick Start

1. Add to pubspec.yaml

dependencies:
  flutter_network_inspector: ^0.1.0

2. Setup (Choose your HTTP client)

For Dio (Recommended)

import 'package:dio/dio.dart';
import 'package:flutter_network_inspector/flutter_network_inspector.dart';

void main() {
  // Setup Dio with interceptor
  final dio = Dio();
  dio.interceptors.add(NetworkInspectorDioInterceptor());
  
  runApp(MyApp());
}

For HTTP Package

import 'package:flutter_network_inspector/flutter_network_inspector.dart';

void main() {
  // Setup HTTP client interceptor
  HttpClientInterceptor.attach();
  
  runApp(MyApp());
}

3. Add Inspector Overlay

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: MyHomePage().withNetworkInspector(), // 👈 Just add this!
    );
  }
}

That's it! 🎉 You'll now see a floating button that shows your network requests.

📖 Detailed Usage

Basic Integration

The simplest way to add network inspection to your app:

// Wrap your app or any widget
MyWidget().withNetworkInspector(
  enabled: true,                    // Enable/disable inspector
  position: Alignment.bottomRight,  // Position of floating button
)

Advanced Integration

For more control, use the NetworkInspectorApp widget:

NetworkInspectorApp(
  enabled: kDebugMode, // Only enable in debug mode
  floatingButtonPosition: Alignment.bottomLeft,
  child: MaterialApp(
    home: MyHomePage(),
  ),
)

Manual Inspector Screen

Open the inspector screen programmatically:

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => InspectorScreen(),
  ),
);

Conditional Setup

Enable only in debug/development builds:

void main() {
  if (kDebugMode) {
    // Setup interceptors only in debug mode
    final dio = Dio();
    dio.interceptors.add(NetworkInspectorDioInterceptor());
    HttpClientInterceptor.attach();
  }
  
  runApp(MyApp());
}

// In your widget
MyApp().withNetworkInspector(enabled: kDebugMode)

🎨 UI Features

Inspector Screen

• Request List: Expandable cards with request summary
• Color Coding:
  • 🟢 Green: Successful responses (2xx)
  • 🔴 Red: Error responses (4xx, 5xx, network errors)
  • 🟠 Orange: Pending requests or redirects (3xx)
  • ⚪ Gray: Cancelled requests

Request Details

• Overview Tab: General information, timing, status
• Request Tab: Request headers and body (formatted JSON)
• Response Tab: Response headers and body (formatted JSON)
• Headers Tab: Complete request and response headers

Search & Filtering

• Search: Find requests by URL, method, or status code
• Filter: Show only successful, failed, or pending requests
• Statistics: Total requests, success rate, average response time

🔧 API Reference

NetworkInspector (Singleton)

final inspector = NetworkInspector.instance;

// Control inspector
inspector.enable();
inspector.disable();
inspector.clearAll();

// Search and filter
inspector.setSearchQuery('api/users');
inspector.setStatusFilter(RequestStatus.error);

// Get statistics
print('Total: ${inspector.totalRequests}');
print('Success: ${inspector.successfulRequests}');
print('Failed: ${inspector.failedRequests}');
print('Avg time: ${inspector.averageResponseTime}');

NetworkRequest Model

class NetworkRequest {
  final String id;
  final String url;
  final HttpMethod method;
  final Map<String, String>? headers;
  final dynamic requestBody;
  final DateTime requestTime;
  final RequestStatus status;
  final int? responseCode;
  final dynamic responseBody;
  final Duration? duration;
  final String? errorMessage;
  
  // Helper methods
  bool get isSuccess;
  bool get hasError;
  String get prettyPrintedRequestBody;
  String get prettyPrintedResponseBody;
}

📝 Examples

Custom Dio Setup

class ApiService {
  late Dio dio;
  
  ApiService() {
    dio = Dio(BaseOptions(
      baseUrl: 'https://api.example.com',
      connectTimeout: Duration(seconds: 5),
      receiveTimeout: Duration(seconds: 3),
    ));
    
    // Add network inspector
    if (kDebugMode) {
      dio.interceptors.add(NetworkInspectorDioInterceptor());
    }
  }
  
  Future<User> getUser(int id) async {
    final response = await dio.get('/users/$id');
    return User.fromJson(response.data);
  }
}

Multiple HTTP Clients

void main() {
  // Setup for multiple HTTP clients
  if (kDebugMode) {
    // For Dio
    final dio = Dio();
    dio.interceptors.add(NetworkInspectorDioInterceptor());
    
    // For http package
    HttpClientInterceptor.attach();
  }
  
  runApp(MyApp());
}

Production Safety

class NetworkConfig {
  static void setup() {
    // Only enable in debug/development
    if (kDebugMode || const String.fromEnvironment('ENV') == 'dev') {
      final dio = Dio();
      dio.interceptors.add(NetworkInspectorDioInterceptor());
      HttpClientInterceptor.attach();
    }
  }
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Clone the repository
2. Run flutter pub get
3. Run the example: cd example && flutter run

📄 License

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

🙋‍♂️ Support

If you like this package, please ⭐ star the repository and share it with other Flutter developers!

For issues and feature requests, please create an issue.

---

Made with ❤️ for the Flutter community