avy_debug_panel

A powerful, customizable in-app developer debug console for Flutter apps. Features gesture triggers, logs viewer, network inspector, device info, storage viewer, feature toggles, and theme customization.

Features

🔧 Debug Overlay - Full-screen modal panel that appears above your app UI
👆 Gesture Triggers - Long press, three-finger tap, or device shake to open
📋 Logs Viewer - Timestamped, searchable logs with level filtering and tags
🌐 Network Inspector - Dio interceptor for HTTP request/response logging
📱 Device Info Panel - Display device model, OS version, app version, build number
💾 Storage Viewer - View all SharedPreferences keys and values
🎚️ Feature Toggles - Runtime feature flag management with categories
🎨 Theme Customization - Multiple built-in themes or create your own
📋 Copy/Export - Copy logs and data to clipboard or export as JSON
🌙 Dark/Light Themes - Clean developer-style UI with multiple color schemes
📑 Tabbed Interface - Organized tabs for Logs, Network, Device, Storage, Features
🧪 Fully Tested - Comprehensive unit and widget tests

Screenshots

Logs Panel	Network Panel	Device Info

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  avy_debug_panel: ^1.0.0

Or install via command line:

flutter pub add avy_debug_panel

Quick Start

1. Initialize and Wrap Your App

import 'package:avy_debug_panel/flutter_debug_panel.dart';

void main() {
  // Initialize the debug panel
  FlutterDebugPanel.init(
    enable: true,
    enableShake: true,
    enableLongPress: true,
    enableThreeFingerTap: true,
  );

  runApp(
    FlutterDebugPanel.wrap(
      MyApp(),
    ),
  );
}

2. Log Messages

import 'package:avy_debug_panel/flutter_debug_panel.dart';

// Basic logging
DebugLogger.log("User logged in");

// With log level
DebugLogger.log("API error", level: LogLevel.error);

// With tag
DebugLogger.log("Network request", tag: "Network");

// Convenience methods
DebugLogger.debug("Debug message");
DebugLogger.info("Info message");
DebugLogger.warning("Warning message");
DebugLogger.error("Error message");

3. Network Inspector (Dio)

import 'package:dio/dio.dart';
import 'package:avy_debug_panel/flutter_debug_panel.dart';

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

// All requests will now be logged
final response = await dio.get('https://api.example.com/data');

4. Feature Flags

import 'package:avy_debug_panel/flutter_debug_panel.dart';

// Register feature flags
DebugFeatureFlags.register(
  'new_checkout',
  'New Checkout Flow',
  description: 'Enable the redesigned checkout experience',
  category: 'Commerce',
  defaultValue: false,
);

// Check if enabled
if (DebugFeatureFlags.isEnabled('new_checkout')) {
  // Show new checkout
}

// Toggle at runtime
DebugFeatureFlags.enable('new_checkout');
DebugFeatureFlags.disable('new_checkout');

Configuration

Basic Configuration

FlutterDebugPanel.init(
  // Enable/disable the entire panel
  enable: true,
  
  // Enable individual gesture triggers
  enableShake: true,
  enableLongPress: true,
  enableThreeFingerTap: true,
  
  // Long press duration before panel opens
  longPressDuration: Duration(seconds: 2),
  
  // Custom colors
  backgroundColor: Color(0xFF1E1E1E),
  accentColor: Colors.cyanAccent,
);

Advanced Configuration with Theme

FlutterDebugPanel.initWithConfig(
  DebugPanelConfig(
    enable: true,
    enableShake: true,
    enableLongPress: true,
    enableThreeFingerTap: true,
    // Use predefined color scheme
    colorScheme: DebugPanelColorScheme.darkPurple,
    // Or provide a completely custom theme
    theme: DebugPanelTheme(
      backgroundColor: Color(0xFF121212),
      surfaceColor: Color(0xFF1E1E1E),
      accentColor: Colors.purple,
      textPrimary: Colors.white,
      textSecondary: Colors.grey,
      successColor: Colors.green,
      warningColor: Colors.orange,
      errorColor: Colors.red,
      infoColor: Colors.blue,
      borderColor: Color(0xFF333333),
    ),
  ),
);

Theming

Built-in Color Schemes

// Dark theme with cyan accent (default)
DebugPanelColorScheme.darkCyan

// Dark theme with purple accent
DebugPanelColorScheme.darkPurple

// Dark theme with green accent
DebugPanelColorScheme.darkGreen

// Dark theme with orange accent
DebugPanelColorScheme.darkOrange

// Light theme with blue accent
DebugPanelColorScheme.lightBlue

Custom Theme

Create your own theme by extending DebugPanelTheme:

const myTheme = DebugPanelTheme(
  backgroundColor: Color(0xFF1A1A2E),
  surfaceColor: Color(0xFF16213E),
  accentColor: Color(0xFFE94560),
  textPrimary: Colors.white,
  textSecondary: Color(0xFFA0A0A0),
  successColor: Color(0xFF4CAF50),
  warningColor: Color(0xFFFF9800),
  errorColor: Color(0xFFF44336),
  infoColor: Color(0xFF2196F3),
  borderColor: Color(0xFF2A2A4A),
  borderRadius: 12.0,
  defaultPadding: 16.0,
  monoFontFamily: 'monospace',
);

Panels Overview

Logs Panel

Displays timestamped log messages
Filter by log level (debug, info, warning, error)
Search functionality
Copy logs to clipboard
Tap to view details
Auto-scroll to latest logs
Export as JSON

Device Panel

App information (name, version, build number)
Device information (model, manufacturer, OS)
System information (platform, Dart version)
Copy any value to clipboard
Platform-specific details (Android, iOS, Web, etc.)

Storage Panel

View all SharedPreferences keys/values
Search functionality
Delete individual keys
Clear all storage
Copy values to clipboard
Type indicators (String, Int, Double, Bool, List)

Features Panel

View all registered feature flags
Toggle flags on/off
Enable/disable all flags
Reset to defaults
Grouped by category
Search functionality

API Reference

FlutterDebugPanel

Method	Description
`init(...)`	Initialize with named parameters
`initWithConfig(config)`	Initialize with config object
`wrap(app)`	Wrap your app widget
`log(message, level, tag)`	Log a message
`clearLogs()`	Clear all logs
`clearNetworkLogs()`	Clear all network logs
`enableFeature(key)`	Enable a feature flag
`disableFeature(key)`	Disable a feature flag
`isFeatureEnabled(key)`	Check if flag is enabled
`config`	Get current configuration
`isEnabled`	Check if panel is enabled

DebugLogger

Method	Description
`log(message, level, tag)`	Log with level and optional tag
`debug(message, tag)`	Log debug message
`info(message, tag)`	Log info message
`warning(message, tag)`	Log warning message
`error(message, tag)`	Log error message
`clear()`	Clear all logs
`export()`	Export logs as string
`exportJson()`	Export logs as JSON
`search(query)`	Search logs
`getLogsByLevel(level)`	Get logs by level
`getLogsByTag(tag)`	Get logs by tag
`addListener(listener)`	Add log listener
`removeListener(listener)`	Remove log listener

DebugNetworkLogger

Method	Description
`logRequest(request)`	Log a network request
`updateRequest(request)`	Update an existing request
`clear()`	Clear all requests
`search(query)`	Search by URL
`getByStatus(success)`	Filter by status
`addListener(listener)`	Add request listener
`removeListener(listener)`	Remove request listener

DebugFeatureFlags

Method	Description
`register(key, name, ...)`	Register a new flag
`registerAll(flags)`	Register multiple flags
`enable(key)`	Enable a flag
`disable(key)`	Disable a flag
`toggle(key)`	Toggle a flag
`set(key, value)`	Set flag to specific value
`isEnabled(key)`	Check if enabled
`getFlag(key)`	Get flag by key
`exists(key)`	Check if flag exists
`unregister(key)`	Remove a flag
`clear()`	Remove all flags
`enableAll()`	Enable all flags
`disableAll()`	Disable all flags
`resetAll()`	Reset all to defaults
`export()`	Export flags as map
`import(values)`	Import flags from map
`allFlags`	Get all flags
`flagsByCategory`	Get flags grouped by category
`categories`	Get all categories
`addListener(listener)`	Add flag change listener
`removeListener(listener)`	Remove listener

LogEntry

Property	Description
`timestamp`	When the log was created
`message`	The log message
`level`	Log level (debug, info, warning, error)
`tag`	Optional category tag
`formattedTimestamp`	Formatted time string
`toMap()`	Convert to map
`toJson()`	Convert to JSON

DebugNetworkRequest

Property	Description
`id`	Unique identifier
`url`	Request URL
`method`	HTTP method
`headers`	Request headers
`body`	Request body
`statusCode`	Response status code
`responseBody`	Response body
`durationMs`	Response time in ms
`isSuccess`	Whether request succeeded
`isError`	Whether request failed
`shortUrl`	URL path without domain
`queryParams`	Query parameters

Best Practices

Only Enable in Debug Mode

FlutterDebugPanel.init(
  enable: kDebugMode,  // Only in debug builds
  enableShake: kDebugMode,
  enableLongPress: kDebugMode,
);

Use Tags for Categorization

DebugLogger.log("User action", tag: "Analytics");
DebugLogger.log("API response", tag: "Network");
DebugLogger.log("Database query", tag: "Database");

Use Log Levels Appropriately

DebugLogger.debug("Verbose debug info");  // Detailed debugging
DebugLogger.info("User logged in");       // Important events
DebugLogger.warning("Slow network");       // Potential issues
DebugLogger.error("API failed");           // Errors

Organize Feature Flags with Categories

DebugFeatureFlags.register('dark_mode', 'Dark Mode', category: 'UI');
DebugFeatureFlags.register('analytics', 'Analytics', category: 'Tracking');
DebugFeatureFlags.register('new_api', 'New API', category: 'Backend');

Architecture

The package follows a clean architecture with:

Core Services: DebugLogger, DebugNetworkLogger, DebugFeatureFlags
Configuration: DebugPanelConfig, DebugPanelTheme
UI Layer: Panels, overlay, and common widgets
Theme System: Customizable theming with color schemes

lib/
├── flutter_debug_panel.dart  # Main entry point
├── logger.dart               # Logger implementation
├── network_logger.dart       # Network logger + Dio interceptor
├── feature_flags.dart        # Feature flags manager
├── debug_overlay.dart        # Overlay widget
├── debug_panel.dart          # Main panel widget
├── panels/
│   ├── logs_panel.dart
│   ├── network_panel.dart
│   ├── device_panel.dart
│   ├── storage_panel.dart
│   └── feature_flags_panel.dart
└── src/
    ├── theme/
    │   └── debug_panel_theme.dart
    ├── widgets/
    │   └── common_widgets.dart
    └── services/
        └── logger_service.dart

Testing

The package includes comprehensive tests. Run them with:

flutter test

Test coverage includes:

Unit tests for all core services
Widget tests for panels and UI components
Integration tests for the debug panel workflow

Dependencies

dio - HTTP client for network interceptor
device_info_plus - Device information
shared_preferences - Storage viewer
shake - Shake gesture detection
intl - Date formatting

Platform Support

Platform	Support
Android	✅
iOS	✅
Web	✅
macOS	✅
Windows	✅
Linux	✅

Changelog

See CHANGELOG.md for a list of changes.

License

MIT License - see LICENSE file.

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting a PR.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone the repo
git clone https://github.com/Avinashrola/avy_debug_panel.git

# Install dependencies
flutter pub get

# Run tests
flutter test

# Run the example app
cd example && flutter run

Issues

Please file issues on the GitHub issue tracker.

Author

Created by Avinash Rola

If you find this package useful, consider sponsoring its development.