log_and_shake #

log_and_shake is a lightweight Flutter package that helps developers log messages and view them via a shake gesture, ideal for debugging during development. It captures print() statements, uncaught exceptions, and shows them in a simple in-app log viewer — triggered by shaking the device. very helpful to show logs while QC team do his work, to easy find the cause of error.

log_and_shake is a lightweight Flutter package that helps developers and QA teams capture and view logs in real time by simply shaking the device.

It automatically records print() or debugPrint() statements and uncaught exceptions, and displays them in an in-app log viewer — making it ideal for debugging during development and QA testing.

🛠 Perfect for use by your QA or QC team to identify issues quickly and gather context before reporting bugs.

✨ Features #

• ✅ Shake the device to show a debug log viewer
• ✅ Captures print() and uncaught errors automatically
• ✅ Simple integration with LogAndShake.run(...)
• ✅ Shake gesture shows a bottom sheet confirmation before opening logs
• ✅ Logging is enabled only in dev mode by default
• ✅ Custom log support: LogAndShake.log("message")
• ✅ Works with any state management or localization (GetX, EasyLocalization, Bloc, etc.)
• ✅ NEW: Timestamps on every log entry
• ✅ NEW: Export logs (share as file or copy to clipboard)
• ✅ NEW: Expandable stack traces with formatted display
• ✅ NEW: Log rotation to prevent memory bloat (configurable max count)
• ✅ NEW: Optional log persistence across app restarts

🚀 Getting Started #

1. Add the package #

dependencies:
  log_and_shake: ^1.1.0

2. 🛠️ Usage ✅ Basic Setup #

In your main.dart:

import 'package:log_and_shake/log_and_shake.dart';

void main() {
  LogAndShake.run(
    appInitializer: () async {
      WidgetsFlutterBinding.ensureInitialized();
      // Optional: await Firebase.initializeApp();
    },
    runAppWidget: const MyApp(),
  );
}

3.✅ Add shake detection and start listening on your app #

Add the navigator key inside your MaterialApp (or GetMaterialApp, etc.):

final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

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

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    LogAndShake.init(navigatorKey: navigatorKey);
  }

  @override
  void dispose() {
    LogAndShake.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
    navigatorKey: navigatorKey,
    home: const HomePage(),
    );
  }
}

📌 Developer Logs #

You can manually log messages anywhere:

LogAndShake.log("Fetching data...");  // auto detect log type
LogAndShake.logI("Fetching data..."); // log info 
LogAndShake.logW("Fetching data..."); // log warning 
LogAndShake.logE("Fetching data..."); // log error 

🔐 Production Safety #

By default, log_and_shake only runs in dev or profile builds.

To disable explicitly:

LogAndShake.run(
  ...,
  enableLogAndShake: false, // disables logs and shake even in dev
);

🆕 Advanced Features #

Log Persistence (NEW in v1.1.0)

Enable log persistence across app restarts:

LogAndShake.run(
  appInitializer: () async {
    WidgetsFlutterBinding.ensureInitialized();
  },
  runAppWidget: const MyApp(),
  persistLogs: true, // Logs will persist across app restarts
);

Configure Maximum Log Count (NEW in v1.1.0)

Prevent memory bloat by setting a maximum log count:

// Set max logs to 500 (default is 1000)
LogAndShake.setMaxLogCount(500);

Export & Share Logs (NEW in v1.1.0)

Users can now:

• Share logs: Tap the menu (⋮) and select "Share Logs" to export as a text file
• Copy all logs: Tap the menu (⋮) and select "Copy All Logs" to clipboard
• Copy individual logs: Long press any log entry to copy it

Stack Trace Formatting (NEW in v1.1.0)

Error logs with stack traces are now:

• Automatically detected and formatted
• Collapsible/expandable for better readability
• Displayed in a clean, formatted view
• Copyable separately from the main error message

Timestamps (NEW in v1.1.0)

Every log entry now shows a precise timestamp in HH:MM:SS.mmm format

📦 Example #

A working example is available in the example/ folder. It demonstrates: Logging a message Triggering an exception Shake-to-open log screen

📮 Feedback & Contributions #

Found a bug or want a new feature? Find an issue, Pull requests are welcome!

📄 License #

MIT License © [MOHAMED EZZELDEEN]

Built with ❤️ to help Flutter developers, and QC team debug faster. #