Flutter Debug Badges

Lightweight debug overlay and section marker badges for Flutter applications. Prints structured markers to the debug console that can be parsed by tools like Dev Pilot into clickable badges.

---

Features

• 📍 Route Overlay — Displays the current route and file name in a top bar (debug mode only). Updates automatically on GoRouter route changes.
• 📄 Section Markers — Wraps any widget to print a section marker to the debug console on every build. Click the visual label to copy the file name.
• 🧩 Dev Pilot Integration — Markers can be parsed by Dev Pilot's DebugOverlayBadges component for clickable badges in the process log.
• 🔤 Custom Route Mapping — Map route paths to custom file names.
• 🏷️ Page Hints — Override the displayed file name for tabs or sub-pages that share the same route.
• 🔄 Section Dedup — Section markers print only once per page navigation to avoid log spam.

Installation

Add to your pubspec.yaml:

dependencies:
  flutter_debug_badges: ^0.1.0

Then run:

flutter pub get

Quick Start

1. Wrap your app with DebugOverlay

import 'package:flutter_debug_badges/flutter_debug_badges.dart';
import 'package:go_router/go_router.dart';

MaterialApp.router(
  routerConfig: router,
  builder: (context, child) {
    return DebugOverlay(
      router: router,
      child: child!,
    );
  },
)

2. Wrap sections with DebugSection

DebugSection(
  fileName: 'dashboard_header.dart',
  child: HeaderWidget(),
)

3. Run in debug mode

flutter run --debug

You will see the overlay bar at the top and markers in the debug console.

Documentation

DebugOverlay

Property	Type	Default	Description
child	Widget	required	The child widget tree to wrap.
router	GoRouter	required	GoRouter instance for route listening.
routeFileMap	Map<String, String>	{}	Custom route-to-file mapping.
defaultFile	String	'app.dart'	Fallback for root route /.
unknownFile	String	'unknown_page.dart'	Fallback for unmatched routes.

DebugOverlay.setPageHint(String? hint)

Override the displayed file name for tabs or sub-pages sharing the same route.

DebugOverlay.setPageHint('profile_tab.dart');   // Set hint
DebugOverlay.setPageHint(null);                  // Reset to route-based mapping

DebugSection

Property	Type	Default	Description
child	Widget	required	The child widget to wrap.
fileName	String	required	File name for the section marker.
fullPage	bool	false	Whether this section wraps a full page.

DebugSection.resetPrinted()

Clears the deduplication history. Called automatically by DebugOverlay on route changes.

Markers Reference

Type	Format	Example
Overlay	[📁 Overlay] {file} | {route}	[📁 Overlay] dashboard_page.dart | /dashboard
Section	[📄 Section] {file}	[📄 Section] dashboard_header.dart
Section Tap	[DebugOverlaySection] 📁 {file}	[DebugOverlaySection] 📁 dashboard_header.dart

Example

A complete working example is available in the example/ directory.

cd example/
flutter run

Requirements

• Dart SDK: >=3.0.0 <4.0.0
• Flutter: >=3.10.0
• GoRouter: >=12.0.0 <18.0.0

License

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