ConsolePlus

ConsolePlus is a Flutter debug helper plugin that shows an in-app debug console accessible via a floating button.
It is intended for debug builds only and will not show or run in release builds when used as directed.

---

Table of Contents

• Features
• Installation
• Quick Start (example)
• API
• Best practices (Debug-only)
• Advanced usage
• Troubleshooting
• Contributing
• License

---

Features

• Floating draggable debug button (configurable by app)
• In-app log viewer with filter (info, warning, error)
• Auto-scroll to latest log
• Export logs as text or JSON (library helper)
• Safe: no UI or logging in release builds if used as documented

---

Installation

Add to your project's pubspec.yaml:

dependencies:
  console_plus:
    path: ../console_plus   # or use published version: ^x.y.z

Then fetch packages:

flutter pub get

---

Quick Start (example)

Example main.dart that starts a periodic timer and shows the floating button to open ConsolePlus:

import 'dart:async';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:console_plus/console_plus.dart';

Timer? _timer;

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MyApp());

  // start timer after UI is built so Overlay exists
  WidgetsBinding.instance.addPostFrameCallback((_) {
    if (kDebugMode) startTimer();
  });
}

void startTimer() {
  _timer = Timer.periodic(const Duration(seconds: 2), (_) {
    final now = DateTime.now();
    // prints to IDE console
    print("⏱ Timer Log: $now");
    // logs to ConsolePlus internal list (debug-only)
    DebugLogConsole.log("⏱ Timer Log: $now");
  });
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('ConsolePlus Demo')),
        body: const Center(child: Text('Tap the bug to view logs')),
        floatingActionButton: kDebugMode
            ? Builder(
                builder: (context) => FloatingActionButton(
                  child: const Icon(Icons.bug_report),
                  onPressed: () => DebugLogConsole.show(context),
                ),
              )
            : null,
      ),
    );
  }
}

---

API

DebugLogConsole.log(String message, {LogType type = LogType.info})

Add a log entry (only active in debug builds).

DebugLogConsole.log("User tapped button", type: LogType.info);
DebugLogConsole.log("Value is null", type: LogType.warning);
DebugLogConsole.log("Unhandled exception", type: LogType.error);

DebugLogConsole.show(BuildContext context)

Show the floating console overlay (must be called with a context inside a MaterialApp / Scaffold).

DebugLogConsole.hide()

Hide the overlay if shown.

DebugLogConsole.exportLogs({bool asJson = false})

Returns the logs as a String in text or JSON format.

---

Best practices (Debug-only)

• The plugin contains kDebugMode guards internally, but still prefer adding kDebugMode around any UI that calls DebugLogConsole.show(context) in your app:

floatingActionButton: kDebugMode
  ? FloatingActionButton(... show console ...)
  : null,

• Start timers or background log sources after the app first frame (WidgetsBinding.instance.addPostFrameCallback) to ensure Overlay exists.

• Do not call DebugLogConsole.show() from main() before runApp().

---

Advanced usage

Listening for logs in your app

If you need to react to new logs in your own UI, ConsolePlus exposes a ValueNotifier:

DebugLogConsole.logsNotifier.addListener(() {
  final logs = DebugLogConsole.logsNotifier.value;
  // update your UI or send logs to a server (only in debug)
});

Exporting logs

final text = await DebugLogConsole.exportLogs();
final json = await DebugLogConsole.exportLogs(asJson: true);

On mobile you can save to a file using path_provider and share with share_plus. On web you can download as a file using a Blob.

---

Troubleshooting

"No Overlay widget found"

• Ensure you call DebugLogConsole.show(context) with a context that belongs to a widget under MaterialApp and Scaffold.
• Use Builder to get a proper inner context:

floatingActionButton: Builder(builder: (ctx) => FloatingActionButton(onPressed: () => DebugLogConsole.show(ctx)))

UI doesn't update when logs are added

• Use DebugLogConsole.logsNotifier to listen for updates; UI must rebuild on notifier change.

Timer stops or UI freezes when console is open

• Don't create timers inside the console widget. Keep timers global or in app-level state and only call DebugLogConsole.log() from the timer callback.
• Avoid heavy setState() calls every time a log arrives; use ValueListenableBuilder or incremental updates.

---

Contributing

PRs welcome. Keep debug-only behaviour intact. If you add native platform code, ensure release builds keep plugin inert unless explicitly enabled.

---

License

MIT © Ashish

console_plus