Firebase Bootstrap Package (notification_kit)

A production-ready, highly configurable, and decoupled Flutter package that completely abstracts Firebase and notification setup. Consuming applications only need a single initialization call inside main() to get a complete notifications ecosystem (FCM, Local Notifications, permissions, background messaging, and notification tap dispatch).

Features

  • Single Call Init: One call to FirebaseBootstrap.start(...) initializes everything.
  • Configurable: Define app name, channels, icons, notification groups, logging, etc.
  • Callbacks-based Architecture: Completely decoupled from GetX, Navigator, or business logic. Handles action dispatches via custom callbacks.
  • Attachment Downloads: Handles downloading notification image attachments for Android.
  • Group Notifications: Supports Android notification channel grouping out of the box.

Installation

Add this package to your pubspec.yaml (when using local workspace):

dependencies:
  notification_kit:
    path: /path/to/notification_kit

Or from pub.dev:

dependencies:
  notification_kit: ^1.0.0

Run:

flutter pub get

Getting Started

Initialize the bootstrap service in your main() method:

import 'package:flutter/material.dart';
import 'package:notification_kit/firebase_bootstrap.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await FirebaseBootstrap.start(
    firebaseOptions: DefaultFirebaseOptions.currentPlatform, // Your generated options
    config: const FirebaseBootstrapConfig(
      appName: "My Consuming App",
      channelId: "default_channel",
      channelName: "General Notifications",
      channelDescription: "All application notifications",
      notificationIcon: "@mipmap/ic_launcher",
      enableLogs: true,
      requestPermissionOnStartup: true,
      showForegroundNotification: true,
      clearNotificationsOnLaunch: true,
    ),
    callbacks: FirebaseBootstrapCallbacks(
      onNotificationTap: (payload) {
        debugPrint("User tapped notification: ${payload.title} - ${payload.body}");
        // Redirect user or navigate using your custom routing solution (e.g. Navigator, GoRouter, GetX)
      },
      onForegroundMessage: (message) {
        debugPrint("Foreground push message received: ${message.messageId}");
      },
      onTokenRefresh: (token) {
        debugPrint("FCM token refreshed: $token");
        // Save the token to your backend database
      },
      onPermissionGranted: () {
        debugPrint("Permissions Granted");
      },
      onPermissionDenied: () {
        debugPrint("Permissions Denied");
      },
    ),
  );

  runApp(const MyApp());
}

Configuration & Callbacks Options

FirebaseBootstrapConfig

Option Type Default Description
appName String Required The consuming app name, used as the fallback notification title.
channelId String Required Android notification channel ID.
channelName String Required User-visible channel name on Android.
channelDescription String "General Notifications" Android notification channel description.
channelGroupId String? null Optional Android notification channel group ID.
channelGroupName String? null Optional Android notification channel group name.
notificationIcon String "@mipmap/ic_launcher" Launch icon name to show in the status bar/alert.
enableLogs bool true Enable internal console logging.
requestPermissionOnStartup bool true Ask for notification permission during start.
showForegroundNotification bool true Force heads-up local alerts when app is open.
clearNotificationsOnLaunch bool true Automatically clear active notifications on init.
logger Function(String, String)? null Optional custom logger function to pipe internal logs.

FirebaseBootstrapCallbacks

Exposes hooks to handle events without locking the package to any routing or state framework:

FirebaseBootstrapCallbacks(
  onNotificationTap: (NotificationPayload payload) { ... },
  onForegroundMessage: (RemoteMessage message) { ... },
  onBackgroundMessage: (RemoteMessage message) { ... },
  onTokenRefresh: (String token) { ... },
  onPermissionDenied: () { ... },
  onPermissionGranted: () { ... },
)

Legacy/Existing Firebase Setup Migration Guide

If you are migrating from a manual Firebase + notification configuration:

  1. Delete Custom Files: Remove your manual NotificationService or firebase setup scripts, including manual listeners on FirebaseMessaging.onMessage, FirebaseMessaging.onMessageOpenedApp, and local notification initializers.
  2. Move Options configuration: Keep your firebase_options.dart file untouched.
  3. Change main(): Integrate the FirebaseBootstrap.start() call inside your main() method before runApp().
  4. Wire Navigation/Routing: In your custom onNotificationTap(payload) callback, read payload.data['screen'] or payload.data['route'] and use your app's router (e.g. GoRouter.of(context).go(...) or Get.to(...)) to navigate to the target screen.
  5. Handle Token Persistence: Instead of writing token savings inside the service, move your storage logic (e.g. SharedPreferences, Hive, secure storage, backend API post) directly inside onTokenRefresh(token). # notification_package

Libraries

notification_kit