Certainly! Here's a detailed README.md for your Flutter error handling package. You can modify the content to suit your specific needs and style.

Flutter Error Handler

A global error handling package for Flutter applications. This package captures and handles both framework-level and asynchronous errors throughout your Flutter app, allowing you to define custom logic for logging or handling errors.

Features

Global error handling: Automatically catches Flutter framework errors.
Async error handling: Catches errors in async operations using runZonedGuarded.
Custom error handling: Allows you to provide a custom error handler for logging or handling errors based on your specific needs (e.g., Firebase Crashlytics, Sentry, or your own logging service).
Pre-app initialization: Supports custom logic before launching the main app (e.g., loading preferences, initializing services).

Installation

Add the following to your pubspec.yaml:

dependencies:
  flutter_error_handler: ^latest

Then, run:

flutter pub get

Usage

To integrate flutter_error_handler into your Flutter application, wrap your app initialization in the provided FlutterErrorHandler.init function.

Basic Example:

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

void main() async {
  // Initialize global error handling with the package
  await FlutterErrorHandler.init(
    app: const MyApp(), // Pass your app widget here
    preAppInitialization: () async {
      // Perform any pre-initialization logic here (e.g., loading preferences)
    },
    onErrorHandler: (Object error, StackTrace stackTrace) {
      // Handle or log the error here
      logErrorToService(error, stackTrace);
    },
  );
}

void logErrorToService(Object error, StackTrace stackTrace) {
  // Example: Log the error to a service like Firebase Crashlytics or Sentry
  print("Logging error: $error");
  print("StackTrace: $stackTrace");
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Error Handler Example')),
        body: Center(
          child: ElevatedButton(
            onPressed: () {
              // Example: Throw a test error
              throw Exception('This is a test error!');
            },
            child: Text('Throw Error'),
          ),
        ),
      ),
    );
  }
}

Parameters

app: Your root widget (MyApp()).
preAppInitialization: A function to perform pre-app initialization tasks, such as loading preferences or setting up configurations. It runs before runApp.
onErrorHandler: A custom error handler function that is invoked whenever an error occurs. This is where you can log errors to an external service or handle errors in a custom way.
showConsoleLogsInDebugMode: To help this check you can control console logs.

Example Use Cases:

Firebase Crashlytics:

import 'package:firebase_crashlytics/firebase_crashlytics.dart';

void logErrorToService(Object error, StackTrace stackTrace) {
  FirebaseCrashlytics.instance.recordError(error, stackTrace);
}

Sentry:

import 'package:sentry_flutter/sentry_flutter.dart';

void logErrorToService(Object error, StackTrace stackTrace) {
  Sentry.captureException(error, stackTrace: stackTrace);
}

Handling Flutter and Async Errors

Flutter Framework Errors: Errors that occur within the Flutter widget tree, such as during build, layout, or rendering, are caught by FlutterError.onError and handled by the global error handler.
Asynchronous Errors: Errors in async operations (e.g., API calls, database operations) are caught using runZonedGuarded, allowing you to handle uncaught async exceptions globally.

Custom Error Handling

You can customize how errors are handled by providing your own onErrorHandler function when calling FlutterErrorHandler.init. This allows you to log errors to a service, display custom error messages, or handle the errors in a way that suits your application’s needs.

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, feel free to open an issue or submit a pull request.

Steps to contribute:

Fork this repository.
Create your feature branch (git checkout -b feature/new-feature).
Commit your changes (git commit -m 'Add some feature').
Push to the branch (git push origin feature/new-feature).
Open a Pull Request.

License

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

Author

Developed by M.Bilal MurtaZa

Example Error Reporting with Firebase:

import 'package:firebase_crashlytics/firebase_crashlytics.dart';

void logErrorToService(Object error, StackTrace stackTrace) {
  FirebaseCrashlytics.instance.recordError(error, stackTrace);
}