🔔 React Native Notification SDK

A production-ready, rule-based notification platform for React Native and Expo applications.

React Native Notification SDK is a production-ready notification platform built for React Native and Expo applications. It enables developers to build dynamic, rule-driven push notification systems powered by Firebase Cloud Messaging (FCM) and Notifee, without writing notification logic throughout the application.

Instead of manually composing notifications every time an event occurs, this SDK allows you to define reusable notification rules, audiences, templates, and deep links, then emit business events while the SDK handles notification generation and delivery automatically.

🚀 Why React Native Notification SDK?

Most notification libraries only provide wrappers around Firebase Cloud Messaging (FCM) or local notifications. While they simplify notification delivery, developers are still responsible for implementing:

• Notification templates
• Audience resolution
• User registration
• Dynamic payload mapping
• Deep linking
• Navigation
• Firebase synchronization
• Business-specific notification logic

React Native Notification SDK solves these problems by introducing a rule-based notification engine that separates business events from notification implementation.

With this SDK, your application simply emits an event, and the SDK automatically:

• Validates the payload
• Resolves notification templates
• Resolves the notification audience
• Generates notification content
• Registers devices
• Delivers push notifications
• Handles deep linking
• Opens the correct screen when a notification is tapped

✨ What's New in Version 2.0.0

Version 2.0.0 is a major release that transforms the SDK from a notification wrapper into a complete notification platform.

New Features

• 🚀 Rule-Based Notification Engine
• 🎯 Dynamic Audience Resolution
• 👥 Audience Types (ALL & USERS)
• 📝 Dynamic Notification Templates
• 🔄 Payload Validation
• 📦 Notification Job Builder
• ☁️ Firebase Firestore Registration
• 👤 Current User Registration APIs
• 🔗 Deep Linking Support
• 🧭 Dynamic Navigation Parameters
• 🖼️ Notification Images
• ⚡ Queue Publisher
• 🛠 SDK CLI
• 🔥 Automatic Firebase Backend Generation
• 📱 Official Playground Application
• 💙 Full TypeScript Support
• ⚛️ React Native & Expo Support

🌟 Key Features

Notification Engine

• Rule-based notification architecture
• Dynamic notification templates
• Dynamic payload interpolation
• Notification validation
• Queue-based notification publishing
• Rich notification support
• Notification images

Audience Targeting

Deliver notifications to:

• All registered users
• Specific users
• Multiple users
• Dynamic users resolved from payload

User Management

Built-in APIs for:

• Registering users
• Updating registered users
• Clearing users
• Fetching current user
• Automatic Firestore synchronization

Deep Linking

Navigate users directly to the correct screen after tapping a notification.

Supports:

• Expo Router
• React Navigation
• Dynamic route parameters
• Template-based navigation values

Firebase Integration

Built on top of Firebase Cloud Messaging.

Supports:

• Firebase Cloud Messaging (FCM)
• Firebase Firestore
• Automatic token registration
• Automatic user synchronization
• Background notifications
• Foreground notifications
• Initial notifications

CLI

Generate Firebase backend configuration automatically.

npx react-native-notification-sdk init

The CLI generates:

• Firebase Functions
• Firestore Rules
• Firestore Indexes
• Firebase Configuration
• Firestore Collections

Developer Experience

• Fully typed API
• TypeScript support
• React Native support
• Expo support
• Production-ready architecture
• Official Playground application
• Real-world notification examples

🏗 Architecture

The SDK follows a rule-driven notification pipeline.

                    Application
                         │
                         ▼
             Notifications.emit(...)
                         │
                         ▼
                 Rule Engine
                         │
                         ▼
              Payload Validator
                         │
                         ▼
              Template Engine
                         │
                         ▼
             Audience Resolver
                         │
                         ▼
          Notification Job Builder
                         │
                         ▼
             Queue Publisher
                         │
                         ▼
          Firebase Firestore
                         │
                         ▼
      Firebase Cloud Messaging (FCM)
                         │
                         ▼
                Push Notification
                         │
                         ▼
             User Taps Notification
                         │
                         ▼
               Deep Link Handler
                         │
                         ▼
          Expo Router / React Navigation
                         │
                         ▼
                Destination Screen

This architecture keeps notification logic centralized, reusable, scalable, and easy to maintain.

🎮 Official Playground

The SDK includes an official Playground application that demonstrates every major feature.

Playground Repository:

https://github.com/udaykiran199715/react-native-notification-sdk-playground

The Playground includes:

• 📱 Device Registration
• 🧪 Notification Explorer
• 🎯 Audience Testing
• 🔔 Notification Preview
• 🔗 Deep Linking
• 🏦 Banking Examples
• 🛒 E-Commerce Examples
• 💬 Chat Examples
• 🏥 Healthcare Examples
• 👨‍💼 HRMS Examples
• 🚚 Logistics Examples
• 🏬 Marketplace Examples
• ☁️ SaaS Examples
• 👥 Social Examples

It serves as the official reference implementation for integrating the SDK into React Native and Expo applications.

📦 NPM Package

Install the latest version from npm:

npm install react-native-notification-sdk

or

yarn add react-native-notification-sdk

Package:

https://www.npmjs.com/package/react-native-notification-sdk

Continue to Part 2 for installation, Firebase setup, CLI initialization, and project configuration.

📥 Installation

Requirements

Before installing the SDK, ensure your project meets the following requirements.

| Requirement | Version | | ---------------- | --------------- | | React Native | 0.81.0 or later | | Expo | SDK 54 or later | | Node.js | 18+ | | Firebase Project | Required | | TypeScript | Recommended |

Install the SDK

Using npm

npm install react-native-notification-sdk

Using Yarn

yarn add react-native-notification-sdk

Peer Dependencies

The SDK is built on top of Firebase Cloud Messaging and Notifee.

Install the required peer dependencies.

npm install \
@react-native-firebase/app \
@react-native-firebase/messaging \
@react-native-firebase/firestore \
@notifee/react-native

or

yarn add \
@react-native-firebase/app \
@react-native-firebase/messaging \
@react-native-firebase/firestore \
@notifee/react-native

Firebase Configuration

Create a Firebase project from the Firebase Console.

https://console.firebase.google.com

Android

Download

google-services.json

Place it inside

android/app/google-services.json

iOS

Download

GoogleService-Info.plist

Place it inside

ios/GoogleService-Info.plist

🛠 SDK CLI

React Native Notification SDK includes a powerful built-in CLI that automates project setup, validation, Firebase deployment, and configuration fixes.

All commands can be executed using:

npx react-native-notification-sdk <command>

Available Commands

| Command | Description | | -------- | -------------------------------------------------------------------------------------------------- | | init | Initializes the SDK and generates the required Firebase backend files. | | fix | Automatically detects and fixes common React Native, Expo, Firebase, and SDK configuration issues. | | doctor | Analyzes the project configuration and reports potential issues before runtime. | | deploy | Deploys the generated Firebase backend resources to your Firebase project. |

Initialize Project

npx react-native-notification-sdk init

This command bootstraps the SDK inside your project.

Generated Files

functions/
.firebaserc
firebase.json
firestore.rules
firestore.indexes.json

What it does

• Generates Firebase Cloud Functions
• Creates Firestore security rules
• Creates Firestore indexes
• Generates Firebase configuration
• Creates the notification queue backend
• Creates user registration collections
• Prepares the project for push notifications

Run this command once after installing the SDK.

Validate Project

npx react-native-notification-sdk doctor

Checks your project configuration.

Validation includes

• React Native version
• Expo compatibility
• Firebase configuration
• Android configuration
• iOS configuration
• Firebase dependencies
• Notifee installation
• Generated backend files
• SDK configuration
• Notification permissions

The command reports configuration issues before they become runtime errors.

Fix Configuration

npx react-native-notification-sdk fix

Automatically fixes common SDK integration problems.

Examples include:

• Missing Firebase configuration
• Incorrect Android setup
• Incorrect iOS setup
• Missing SDK configuration
• Notification configuration issues
• Firebase dependency issues
• Project structure inconsistencies

Use this command whenever the Doctor command reports recoverable issues.

Deploy Firebase Backend

npx react-native-notification-sdk deploy

Deploys the generated Firebase backend.

The deployment includes:

• Firebase Cloud Functions
• Firestore Security Rules
• Firestore Indexes
• Notification Queue
• Backend configuration

Equivalent Firebase commands are executed automatically, allowing you to deploy the backend without manually invoking the Firebase CLI.

Recommended CLI Workflow

For a new project, the recommended setup process is:

# Install SDK
npm install react-native-notification-sdk

# Initialize SDK
npx react-native-notification-sdk init

# Verify project configuration
npx react-native-notification-sdk doctor

# Automatically fix detected issues (if any)
npx react-native-notification-sdk fix

# Deploy Firebase backend
npx react-native-notification-sdk deploy

Once these steps are complete, initialize the SDK in your application, register your notification rules, and begin emitting business events.

These files are required for:

• Firebase Cloud Functions
• Firestore Collections
• Firestore Security Rules
• Firestore Indexes
• Notification Queue
• User Registration
• Device Registration

Note

The generated files should be committed to your project repository because they are part of your application's Firebase backend configuration.

React Native Configuration

Android

Ensure Firebase is configured correctly.

apply plugin: "com.google.gms.google-services"

Also ensure the following permission exists.

<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

For Android 13+ notification permission is required.

iOS

Enable the following capabilities inside Xcode.

• Push Notifications
• Background Modes

Background Modes should include:

• Remote Notifications

Also upload your APNs Authentication Key to Firebase.

Firebase Console

↓

Project Settings

↓

Cloud Messaging

↓

Upload APNs Authentication Key

Expo Support

The SDK fully supports Expo Development Builds.

Generate native projects.

npx expo prebuild

Install CocoaPods.

cd ios
pod install

Then build.

npx expo run:android

or

npx expo run:ios

Note

Expo Go is not supported because Firebase Messaging and Notifee require native modules.

Initialize the SDK

Initialize the SDK once when your application starts.

Example:

import Notifications from "react-native-notification-sdk";

await Notifications.initialize({
  firebase: {
    android: {
      defaultChannelId: "default",
    },
  },
});

Initialization automatically:

• Configures Firebase Messaging
• Creates notification channels
• Registers foreground listeners
• Registers background listeners
• Handles notification taps
• Synchronizes the FCM token
• Restores the registered user
• Prepares the notification engine

This method should be called only once during application startup.

Verify Installation

You can verify that the SDK has been initialized successfully.

const status = await Notifications.getStatus();

console.log(status);

Example response.

{
    initialized: true,
    permission: "authorized",
    token: "fcm_token..."
}

Next Step

Once the SDK has been initialized successfully, continue with:

• Creating Notification Rules
• Registering Users
• Emitting Notifications
• Configuring Deep Links

The following sections cover these topics in detail.

⚙️ Rule Engine

One of the core features introduced in Version 2.0.0 is the Rule Engine.

Instead of manually building notifications throughout your application, the SDK allows you to define notification rules declaratively.

Your application simply emits business events, and the SDK automatically determines:

• Who should receive the notification
• What the notification should contain
• Which image should be displayed
• Which screen should open
• Which navigation parameters should be passed

This keeps notification logic centralized, reusable, and easy to maintain.

Notification Rule

A notification rule defines how a business event should be transformed into a push notification.

Example:

{
    event: BankingEvents.TRANSACTION_SUCCESS,

    enabled: true,

    audience: {
        type: AudienceType.USERS,
        sources: ["customerId"],
    },

    notification: {
        title: "💳 Transaction Successful",
        body: "₹{{amount}} has been debited successfully.",
        image: "{{image}}",
    },

    navigation: {
        route: "/banking",
        params: {
            transactionId: "{{transactionId}}",
        },
    },
}

Rule Structure

Every notification rule consists of the following sections.

| Property | Description | | ------------ | --------------------------------------------- | | event | Business event that triggers the notification | | enabled | Enables or disables the rule | | audience | Determines notification recipients | | notification | Notification title, body and image | | navigation | Deep-link destination |

Registering Rules

Create your notification rules.

Example:

export const BankingRules: NotificationRule[] = [
    ...
];

Combine all module rules.

export const Rules: NotificationRule[] = [
  ...BankingRules,
  ...EcommerceRules,
  ...ChatRules,
  ...HealthcareRules,
  ...HrmsRules,
  ...LogisticsRules,
  ...MarketplaceRules,
  ...SaasRules,
  ...SocialRules,
];

Initialize the SDK with the registered rules.

Notifications.initialize({
  rules: Rules,
});

The SDK automatically compiles all rules during initialization.

Template Engine

Notification templates support dynamic placeholders.

Example:

notification: {
    title: "Welcome {{customerName}}",
    body: "Your order #{{orderId}} has been confirmed.",
}

Payload

{
    customerName: "John",
    orderId: "ORD-1001",
}

Resolved notification

Title

Welcome John

Body

Your order #ORD-1001 has been confirmed.

Supported Template Values

Templates support any payload property.

{{customerName}}

{{amount}}

{{transactionId}}

{{orderId}}

{{employeeName}}

{{department}}

{{doctorName}}

{{driverName}}

Nested properties are also supported.

Example

{{customer.name}}

{{customer.address.city}}

{{order.total}}

Audience Resolution

The SDK supports multiple audience types.

AudienceType.ALL

Deliver the notification to every registered user.

Example

audience: {
    type: AudienceType.ALL,
}

AudienceType.USERS

Deliver notifications only to specific users.

Example

audience: {
    type: AudienceType.USERS,
    sources: ["customerId"],
}

Payload

{
  customerId: "CUS-1001";
}

The SDK resolves the user ID from the payload, finds the registered device in Firestore, and sends the notification only to that user.

Multiple Users

The SDK also supports notifying multiple users.

Example

audience: {
    type: AudienceType.USERS,
    sources: ["customerIds"],
}

Payload

{
  customerIds: ["CUS-1001", "CUS-1002", "CUS-1003"];
}

The SDK automatically resolves all user IDs and removes duplicate values before publishing the notification.

User Registration

To receive targeted notifications, register the currently logged-in user.

await Notifications.setCurrentUser({
  id: "CUS-1001",
  metadata: {
    name: "John Doe",
  },
});

The SDK automatically stores:

• User ID
• FCM Token
• Metadata

inside Firebase Firestore.

Get Current User

Retrieve the currently registered user.

const user = await Notifications.getCurrentUser();

Clear Current User

Clear the current user when logging out.

await Notifications.clearCurrentUser();

This removes the registered device mapping from Firestore.

Emitting Notifications

Once the SDK has been initialized and rules have been registered, notifications can be emitted by publishing business events.

Example

await Notifications.emit(BankingEvents.TRANSACTION_SUCCESS, {
  id: "evt-001",

  data: {
    customerId: "CUS-1001",
    amount: 2500,
    transactionId: "TXN-1001",
    image: "...",
  },
});

The SDK automatically performs the following steps.

Business Event

↓

Find Rule

↓

Validate Payload

↓

Resolve Templates

↓

Resolve Audience

↓

Build Notification

↓

Publish Notification

No additional notification logic is required inside the application.

Deep Linking

Rules can define navigation destinations.

Example

navigation: {
    route: "/banking",
    params: {
        transactionId: "{{transactionId}}",
    },
}

When the user taps the notification, the SDK automatically navigates to the configured route and passes the resolved parameters.

This works with:

• Expo Router
• React Navigation

Notification Images

Images can also be resolved dynamically.

Example

notification: {
    image: "{{image}}",
}

Payload

{
  image: "https://example.com/banner.jpg";
}

The image URL is automatically resolved before the notification is displayed.

Rule Validation

During notification processing, the SDK validates:

• Rule existence
• Audience configuration
• Payload structure
• Template placeholders
• Navigation configuration

If a rule cannot be found or the payload is invalid, descriptive errors are thrown to simplify debugging during development.

Best Practices

✔ Group rules by business domain.

✔ Keep notification templates inside rules instead of application code.

✔ Register users immediately after login.

✔ Clear users during logout.

✔ Use meaningful event names.

✔ Keep navigation routes stable.

✔ Prefer dynamic templates over manually composing notification text.

✔ Use the official Playground to validate new rules before integrating them into production applications.

📚 API Reference

The SDK exposes a simple, fully typed API for initializing the notification engine, managing permissions, registering users, and emitting notifications.

SDK Initialization

Initialize the SDK once during application startup.

import Notifications from "react-native-notification-sdk";

await Notifications.initialize({
  rules: Rules,
});

Note

The SDK should only be initialized once during application startup.

Permission APIs

Request Notification Permission

Requests notification permission from the user.

const status = await Notifications.requestPermission();

Returns:

{
  permission: "AUTHORIZED";
}

Get Permission Status

Retrieve the current notification permission.

const status = await Notifications.getStatus();

Example

{
    initialized: true,
    permission: "AUTHORIZED",
    token: "fcm_token..."
}

Device APIs

Get FCM Token

Retrieve the current Firebase Cloud Messaging token.

const token = await Notifications.getToken();

Current User

Register User

Registers the currently authenticated user.

await Notifications.setCurrentUser({
  id: "CUS-1001",
  metadata: {
    name: "John Doe",
  },
});

The SDK automatically:

• Stores the user in Firestore
• Associates the FCM token
• Updates existing registrations
• Synchronizes future token refreshes

Get Current User

const user = await Notifications.getCurrentUser();

Returns

{
    id: "CUS-1001",
    metadata: {
        name: "John Doe",
    }
}

Clear Current User

await Notifications.clearCurrentUser();

This should be called during logout to remove the user-to-device mapping.

Notification APIs

Emit Notification

Emit a business event.

await Notifications.emit(BankingEvents.TRANSACTION_SUCCESS, {
  id: "evt-001",
  data: {
    customerId: "CUS-1001",
    amount: 2500,
    transactionId: "TXN-1001",
  },
});

The SDK automatically:

• Finds the matching rule
• Validates the payload
• Resolves templates
• Resolves recipients
• Creates the notification
• Publishes the notification

Local Notifications

Display an immediate local notification.

await Notifications.displayNotification({
  title: "Hello",
  body: "Welcome to React Native Notification SDK",
});

Scheduled Notifications

Schedule notifications for a future date and time.

await Notifications.scheduleNotification({
  title: "Reminder",
  body: "Don't forget your meeting.",
  timestamp: Date.now() + 60 * 60 * 1000,
});

Cancel Notifications

Cancel a scheduled notification.

await Notifications.cancelNotification(notificationId);

Cancel all scheduled notifications.

await Notifications.cancelAllNotifications();

Badge APIs

Update the application badge.

await Notifications.setBadgeCount(5);

Retrieve the current badge count.

const badge = await Notifications.getBadgeCount();

Reset the badge count.

await Notifications.resetBadgeCount();

Notification Channels

Create a notification channel.

await Notifications.createChannel({
  id: "orders",
  name: "Orders",
});

Retrieve all notification channels.

const channels = await Notifications.getChannels();

Delete a notification channel.

await Notifications.deleteChannel("orders");

Event Listeners

Listen for foreground notifications.

const unsubscribe = Notifications.onForegroundNotification((notification) => {
  console.log(notification);
});

Listen for notification press events.

const unsubscribe = Notifications.onNotificationPress((event) => {
  console.log(event);
});

Retrieve the notification that launched the application.

const notification = await Notifications.getInitialNotification();

API Summary

| API | Description | | -------------------------- | -------------------------------- | | initialize() | Initializes the SDK | | requestPermission() | Requests notification permission | | getStatus() | Returns SDK status | | getToken() | Returns FCM token | | setCurrentUser() | Registers current user | | getCurrentUser() | Returns current user | | clearCurrentUser() | Removes current user | | emit() | Emits business events | | displayNotification() | Displays local notification | | scheduleNotification() | Schedules notification | | cancelNotification() | Cancels a notification | | cancelAllNotifications() | Cancels all notifications | | createChannel() | Creates notification channel | | getChannels() | Returns notification channels | | deleteChannel() | Deletes notification channel | | setBadgeCount() | Sets badge count | | getBadgeCount() | Gets badge count | | resetBadgeCount() | Clears badge count | | onForegroundNotification() | Foreground notification listener | | onNotificationPress() | Notification press listener | | getInitialNotification() | Returns launch notification |

🎮 Official Playground

The SDK includes an official Playground application that demonstrates every major feature.

GitHub Repository

https://github.com/udaykiran199715/react-native-notification-sdk-playground

The Playground demonstrates:

• SDK initialization
• Notification permissions
• Device registration
• User registration
• Rule Engine
• Template Engine
• Audience Resolution
• Notification Preview
• Business Scenarios
• Deep Linking
• Expo Router Integration
• Firebase Integration
• End-to-end notification testing

It is the recommended project for learning and validating SDK integrations.

💡 Best Practices

Organize Rules by Module

Keep notification rules grouped by business domain.

Examples:

• Banking
• E-Commerce
• Healthcare
• HRMS
• Logistics

This improves maintainability.

Register Users After Login

Register users immediately after successful authentication.

await Notifications.setCurrentUser(user);

Clear Users During Logout

await Notifications.clearCurrentUser();

Keep Business Logic Separate

Avoid manually constructing notifications.

Instead, emit business events and allow the Rule Engine to generate notifications.

Validate Using the Playground

Before deploying new notification rules to production, verify them using the official Playground application.

🔍 Troubleshooting

Notifications Not Received

Verify:

• Firebase is configured correctly.
• Notification permission has been granted.
• The FCM token is available.
• The current user has been registered.
• The notification rule exists.
• The Firebase backend has been deployed.

AudienceType.USERS Not Working

Verify:

• The user has been registered using setCurrentUser().
• The payload contains the configured audience source.
• The audience source resolves to the expected user ID.
• Firestore contains the user registration.

Deep Linking Not Working

Verify:

• The notification rule contains a valid route.
• The application has configured deep-link handling.
• Navigation parameters resolve correctly.

Invalid Payload Errors

Ensure the emitted payload satisfies the notification rule requirements and contains all required template values.

❓ Frequently Asked Questions

Does the SDK support Expo?

Yes.

The SDK supports Expo Development Builds using Expo Router and native modules.

Does the SDK support React Native CLI?

Yes.

The SDK supports standard React Native CLI applications.

Can I send notifications to all users?

Yes.

Use:

AudienceType.ALL;

Can I send notifications to selected users?

Yes.

Use:

AudienceType.USERS;

and configure the appropriate audience sources.

Can I notify multiple users?

Yes.

The audience resolver accepts arrays of user IDs and automatically removes duplicate values.

Can I use dynamic templates?

Yes.

Templates support payload interpolation using placeholders such as:

{{customerName}}

{{amount}}

{{orderId}}

Does the SDK support deep linking?

Yes.

Navigation routes and parameters can be configured directly within notification rules.

🗺 Roadmap

Future improvements planned for upcoming releases include:

• Analytics integration
• Delivery tracking
• Notification history
• Segmented audiences
• Scheduled rule execution
• Rich media enhancements
• Dashboard tooling
• Additional CLI commands
• Extended automation capabilities

📄 Changelog

Version 2.0.0

Added

• Rule Engine
• Template Engine
• Audience Resolution
• User Registration
• Firestore Synchronization
• Queue Publisher
• Notification Job Builder
• Deep Linking
• Dynamic Navigation
• SDK CLI
• Official Playground
• TypeScript Improvements
• Expo Support

Improved

• Developer Experience
• Firebase Integration
• Notification Architecture
• Audience Management
• Payload Validation

Thank you for using React Native Notification SDK.

If you find this project useful, consider exploring the official Playground and sharing feedback to help improve future releases.