console_plus - Dart API docs

ConsolePlus

Pub package: https://pub.dev/packages/console_plus
Repository: https://github.com/ashish8381/console_plus

A floating in-app console for Flutter — view, filter, search & export logs while your app runs!
console_plus lets you debug on-device with a floating overlay console that captures print() and debugPrint() in real time.

🆕 Version 2.0.0 & 2.0.1 Highlights

🚀 Major Rewrite for Stability & Zone Safety

🧭 Zone-safe initialization — no more “Zone mismatch” errors.
🪄 Unified log capture — print() + debugPrint() + platform errors all logged automatically.
🧩 Cleaner API — single ConsolePlus.initApp() entry point.
🎨 Redesigned console UI — smoother, resizable, searchable overlay.
🧪 Better Flutter Test compatibility — works seamlessly inside test zones.

✨ Features

✅ Floating draggable console overlay
✅ Logs display above your app’s UI (non-blocking)
✅ Captures print() and debugPrint()
✅ Auto-scroll when near the bottom
✅ Filter logs by type (INFO, WARNING, ERROR)
✅ Keyword search for tags or text
✅ Runtime toggle: high-performance (virtualized) vs full-text mode
✅ Saved search queries per profile
✅ Command palette (pause, clear, export templates, copy filtered logs)
✅ Optional custom actions API for console extensions
✅ Copy, clear, and export logs as JSON
✅ Built-in floating 🐞 debug button
✅ Captures FlutterError and PlatformDispatcher errors
✅ Compatible with Flutter 3.16+ / Dart 3+

⚙️ Installation

Add to your pubspec.yaml:

dependencies:
  console_plus: ^2.0.2

Then fetch packages:

flutter pub get

Import it:

import 'package:console_plus/console_plus.dart';

💻 Usage

Step 1 — Initialize ConsolePlus

Wrap your app inside ConsolePlus.initApp():

Future<void> main() async {
  await ConsolePlus.initApp(
    const MyApp(),
    interceptPrints: true,          // Capture print() and debugPrint()
    captureFlutterErrors: true,     // Capture Flutter framework errors
    capturePlatformErrors: true,    // Capture platform dispatcher errors
  );
}

🧠 This ensures WidgetsFlutterBinding and runApp() are initialized in the same zone — no more zone mismatch errors!

Step 2 — Show Floating Debug Button

FloatingDebugButton.show(context);

This shows a draggable 🐞 button that opens the console overlay.

Step 3 — Log Messages

Use:

DebugLogConsole.log("User logged in successfully");
DebugLogConsole.log("Missing field: email", type: LogType.warning);
DebugLogConsole.log("API request failed", type: LogType.error);

Or just use:

print("Something happened");
debugPrint("App started!");

Both are automatically captured by ConsolePlus.

Switch rendering mode at runtime:

DebugLogConsole.highPerformanceMode = true; // virtualized, faster
DebugLogConsole.highPerformanceMode = false; // full selectable text block

Saved queries profile + custom actions:

await DebugLogConsole.setSavedQueryProfile('qa-staging');

DebugLogConsole.registerCustomAction(
  ConsoleCustomAction(
    id: 'quick-note',
    label: 'Add Quick Note',
    icon: Icons.note_add_outlined,
    onExecute: (context, filteredLogs) async {
      DebugLogConsole.addLog('Quick note | filtered: ${filteredLogs.length}');
    },
  ),
);

Mode Selection Guide

Expected Log Volume	Recommended Mode	Why
`< 500` logs/session	`Full-text`	Best for copy/select across one continuous block
`500 - 2000` logs/session	`High-performance`	Better frame stability while preserving per-line selection
`2000+` logs/session or burst logging	`High-performance`	Strongest protection against UI jank and input lag

Step 4 — Export Logs

Tap the ⬇️ Download icon in the console header to export as a .json file.

You can also programmatically call:

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

🎛️ Console UI

🟢 Floating, draggable, and resizable window
🔍 Search bar with keyword filtering
🧩 Filter by log levels (Info / Warning / Error)
📋 Copy, ⬇️ Export, 🗑️ Clear logs
📜 Persistent scroll + multi-line selection
⚡ Real-time updates powered by ValueNotifier

🧩 Example (Benchmark App)

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

Future<void> main() async {
  await ConsolePlus.initApp(
    const ConsolePlusExampleApp(),
    interceptPrints: true,
    captureFlutterErrors: true,
    capturePlatformErrors: true,
  );
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'ConsolePlus Benchmark',
      theme: ThemeData.dark(useMaterial3: true),
      home: const BenchmarkPage(),
    );
  }
}

The example app now includes:

Runtime mode switch (High Performance Mode)
Run 1k Benchmark and Run 5k Benchmark buttons
Live metrics: enqueue time, first UI update latency, settle time, estimated FPS

Open example/lib/main.dart for the full benchmark implementation.

📂 File Export

Format: .json

Example output:

[
  {
    "timestamp": "2025-11-08T12:30:01.345Z",
    "type": "info",
    "message": "App started"
  },
  {
    "timestamp": "2025-11-08T12:31:14.123Z",
    "type": "error",
    "message": "Network timeout"
  }
]

🧭 Upgrading from v1.x → v2.0.1

Before:

void main() {
  ConsolePlus.init(MyApp());
  runApp(MyApp());
}

After (v2.0.0):

Future<void> main() async {
  await ConsolePlus.initApp(
    const MyApp(),
    interceptPrints: true,
    captureFlutterErrors: true,
    capturePlatformErrors: true,
  );
}

✅ ConsolePlus.init() → replaced with ConsolePlus.initApp() ✅ Initialization now must be awaited ✅ Zone-safe by default — fixes zone mismatch crashes ✅ No more manual WidgetsFlutterBinding.ensureInitialized() calls required

Contributing

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

📜 License

💬 Credits

Built with ❤️ by Ashish Follow for updates and Flutter dev tips!