https://github.com/liquidatorcoder/flutter_debug_tools
A set of interactive, in-app tools for diagnosing UI and performance issues in Flutter apps—no external tooling required.
https://github.com/liquidatorcoder/flutter_debug_tools
android debugging flutter flutter-package ios
Last synced: 3 months ago
JSON representation
A set of interactive, in-app tools for diagnosing UI and performance issues in Flutter apps—no external tooling required.
- Host: GitHub
- URL: https://github.com/liquidatorcoder/flutter_debug_tools
- Owner: LiquidatorCoder
- License: mit
- Created: 2024-03-06T09:15:13.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-06T13:06:49.000Z (over 1 year ago)
- Last Synced: 2025-04-08T12:26:48.758Z (about 1 year ago)
- Topics: android, debugging, flutter, flutter-package, ios
- Language: Dart
- Homepage: https://pub.dev/packages/flutter_debug_tools
- Size: 5.01 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
In-app debug tools for Flutter UI, rendering, logs, navigation, and device diagnostics - no context switching required.
Features •
Installation •
Quick Start •
Debug Logs •
Tips •
License
---
| Screenshots | | |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| 
| 
| 
|
| 🧲 **Edge tray launcher** docked to the right side; draggable and always accessible. | 🧾 **Version ticker** displaying app, FlutterLens, Flutter, Dart, and build mode details. | 📋 **Bottom sheet tools grid** with active/inactive visual states and quick toggles. |
| 
| 
| 
|
| 📱 **In-app debug logs** to inspect console logs inside the running app. | 🎨 **Color result card** showing selected color in HEX, RGB, and HSL with copy action. | ⚡ **Device details** to quickly check and share device details. |
| 
| 
| 
|
| 🎛️ **Animation toolbox** with global speed, pause/disable toggles, frame timing HUD, and animated-region highlighting controls. | 📈 **Frame timing HUD in context** showing live FPS, average frame time, and max frame time over the app surface. | 🌐 **Network inspector list view** with status filters, HTTP methods, durations, and retry markers for requests. |
| 
| | |
| 🔎 **Network request details sheet** with URL, method, status, duration, and request/response headers for deep inspection. | | |
---
## ✨ Features
- 🧭 **Screen Name Overlay**: See the active route/screen while navigating.
- 📋 **Debug Logs Viewer**: Capture and inspect console logs inside the running app.
- 🌐 **Network Inspector**: Capture request/response timing, headers, payloads, failures, and retry attempts.
- 📱 **Device Details**: Inspect model, OS, screen metrics, and hardware info in-app.
- 🎯 **Color Picker**: Pick any on-screen pixel color quickly.
- 🧱 **Debug Paint / Layout Insights**: Visualize layout boundaries and spacing behavior.
- 🌈 **Repaint Rainbow**: Spot frequent repaints to detect expensive widgets.
- 🎛️ **Animation Toolbox**: Control animation speed, pause, disable animations, frame timing HUD, and animated-region highlights.
- Includes global curve presets (for example: `System`, `Linear`, `Ease In Out`, `Bounce Out`, and more) for animations that opt into FlutterLens curve scope.
- ⚡ **Performance Overlay Toggle**: Enable Flutter performance overlay directly from the panel.
- 🧲 **Edge Tray Launcher**: Open FlutterLens from a draggable edge tray.
- 🧾 **Version Ticker**: Live ticker for app/build/flutter/dart/FlutterLens versions.
- 🎨 **Picked Color Card**: View HEX/RGB/HSL + copy from the panel.
- 💾 **Sticky Debug Toggles**: Core flags are persisted across launches.
### 🧰 Tool-by-tool quick map
- `Debug Paint` → toggles `debugPaintSizeEnabled`
- `Size Info` → enables render box inspector overlay
- `Repaint Rainbow` → toggles `debugRepaintTextRainbowEnabled`
- `Debug Logs` → opens in-app logs viewer
- `Network Inspector` → opens in-app request/response inspector
- `Perf Overlay` → toggles `showPerformanceOverlay`
- `Color Picker` → pixel pick + color card/copy flow
- `Device Details` → opens device info sheet
- `Screen Name` → route name overlay (with `DebugNavigatorObserver`)
- `Animation Toolbox` → animation speed/pause/disable/highlight controls
---
## 📦 Installation
Add this to your `pubspec.yaml`:
```yaml
dependencies:
flutter_debug_tools: ^2.0.5
```
Then run:
```bash
flutter pub get
```
---
## 🚀 Quick Start
```dart
import 'package:flutter/material.dart';
import 'package:flutter_debug_tools/flutter_debug_tools.dart';
Future main() async {
await DebugLogCapture.runApp(() async {
runApp(const MyApp());
});
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
final navigatorObserver = DebugNavigatorObserver();
return FlutterLens(
builder: (context, showPerformanceOverlay, child) {
return MaterialApp(
title: 'FlutterLens Demo',
showPerformanceOverlay: showPerformanceOverlay,
navigatorObservers: [navigatorObserver],
home: const Placeholder(),
);
},
);
}
}
```
### 🧩 Minimal integration (without log zone wrapper)
```dart
import 'package:flutter/material.dart';
import 'package:flutter_debug_tools/flutter_debug_tools.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return FlutterLens(
builder: (context, showPerformanceOverlay, child) {
return MaterialApp(
showPerformanceOverlay: showPerformanceOverlay,
home: const Placeholder(),
);
},
);
}
}
```
### 🎚️ Opt animations into global curve override
Animation Toolbox curve presets apply to animations that resolve their curve from `FlutterLensAnimationCurveScope`:
```dart
final curve = FlutterLensAnimationCurveScope.resolve(context, Curves.easeInOutCubic);
AnimatedContainer(
duration: const Duration(milliseconds: 500),
curve: curve,
child: const Placeholder(),
)
```
### 🎛️ Disable in non-debug environments
```dart
FlutterLens(
isEnabled: kDebugMode,
builder: (context, showPerformanceOverlay, child) {
return MaterialApp(
showPerformanceOverlay: showPerformanceOverlay,
home: const HomeScreen(),
);
},
)
```
---
## 🧾 Debug Logs (How It Works)
- ✅ Captures Dart-side console logs (including `print` output in the wrapped zone)
- ✅ Captures framework/platform error callbacks and shows them in the logs viewer
- ✅ Lets you filter logs by level (`All`, `Info`, `Warn`, `Error`, `Debug`)
- ✅ Tap any log row to copy it to clipboard
If you already use another logger, you can still use it; FlutterLens will continue showing captured console/error output in the viewer.
### 🔎 What gets captured
- `print(...)` output (inside `DebugLogCapture.runApp` zone)
- `FlutterError.onError`
- `PlatformDispatcher.instance.onError`
- uncaught zoned async exceptions
### 📚 Public logging APIs
- `DebugLogCapture.install()`
- `DebugLogCapture.runApp(() async { ... })`
- `DebugLogStore.instance.add(...)`
- `DebugLogStore.instance.clear()`
---
## 🧭 Navigation integration
To populate route names in the `Screen Name` overlay, attach `DebugNavigatorObserver`:
```dart
MaterialApp(
navigatorObservers: [DebugNavigatorObserver()],
home: const HomeScreen(),
)
```
---
## 🖱️ Panel interactions
- Swipe down on the panel to dismiss.
- Tap outside the panel to dismiss.
- Drag the right-edge tray up/down to reposition.
- Tap the tray to open FlutterLens.
### 🌐 Network Inspector coverage
- Captures requests made through `dart:io` `HttpClient` (including typical `package:http` usage on Android/iOS/desktop).
- Does not capture web `fetch/XHR` traffic.
---
## 💡 Tips
- Use FlutterLens only in debug/dev environments.
- Add `DebugNavigatorObserver` for better route visibility in overlays.
- Keep an eye on `Repaint Rainbow` + `Performance Overlay` together for quick perf diagnosis.
- Use `FlutterLensAnimationCurveScope.resolve(...)` in your app animations when you want Animation Toolbox curve overrides to affect them.
- Network Inspector currently targets `dart:io` `HttpClient` traffic.
- If Dart/Flutter versions show fallback values, pass build-time dart-defines for those keys.
---
## 🙌 Credits
Built with:
- [shared_preferences](https://pub.dev/packages/shared_preferences)
- [device_info_plus](https://pub.dev/packages/device_info_plus)
---
## 🐞 Bugs or Requests
- Bug report: [Open issue](https://github.com/LiquidatorCoder/flutter_debug_tools/issues/new?template=bug_report.md)
- Feature request: [Open request](https://github.com/LiquidatorCoder/flutter_debug_tools/issues/new?template=feature_request.md)
- PRs are welcome! 🎉
---
## 📄 License
MIT License