react-native-notify-kit 10.0.0 - FCM Mode is here!

[marcocrupi]

What was broken before

If you've ever tried to use @notifee/react-native (or this fork) as the display layer for Firebase Cloud Messaging, you've hit one of these two walls:

Wall 1: duplicate notifications.
You send an FCM notification payload. The OS auto-displays it via the FCM SDK. Then your setBackgroundMessageHandler fires and calls displayNotification() — and now the user sees the same push twice. Every. Single. Time.

Wall 2: silent-push drops.
OK, so you switch to FCM data-only payloads. No more duplicates on Android. But now iOS treats every push as a silent / background push — and Apple throttles those aggressively. In production, on real devices, you lose 30–60% of your pushes. Low Power Mode? Worse. App force-quit? Worse. Your users never see the notification and you have no idea why.

There was no third option. You either duplicated or dropped. Forty-plus people asked for a fix over the years on invertase/notifee#129, and the issue was closed not planned.

This release is that third option.

What's new in 10.0.0

Notifee FCM Mode — use react-native-notify-kit as the sole display layer for FCM pushes on both Android and iOS, with no duplicates and no silent-push drops. One developer API hides the platform asymmetry.

The trick: it sends a different FCM payload shape per platform under the hood.

• Android gets a data-only payload → your client handler renders the notification with full Notifee control. No FCM auto-display, no duplicate.
• iOS gets an APNs alert payload with mutable-content: 1 → APNs delivers it reliably (~99%, not silent-push throttled), and a Notification Service Extension reads the same notifee_options blob and applies your styling before the OS draws it.
• You write one payload server-side. The SDK handles the split.

What you get

• Server SDK — buildNotifyKitPayload(input) from react-native-notify-kit/server. Zero runtime deps, works in Node.js and Firebase Cloud Functions.
• Client handler — notifee.handleFcmMessage(remoteMessage). One line in setBackgroundMessageHandler / onMessage.
• CLI — npx react-native-notify-kit init-nse scaffolds the iOS Notification Service Extension (Swift), patches your Podfile, wires .pbxproj. No more manual Xcode ceremony, no more bridging header hunts.
• Full Notifee control: channels, actions, BIG_TEXT, BIG_PICTURE, categories, thread-id, interruption level, attachments, custom sounds — all driven from server-side, delivered reliably, displayed once.

Quick start

// Server
import { buildNotifyKitPayload } from 'react-native-notify-kit/server';
await admin.messaging().send(buildNotifyKitPayload({
  token,
  notification: { title, body, android: { channelId }, ios: { sound: 'default' } },
}));

// Client
messaging().setBackgroundMessageHandler(notifee.handleFcmMessage);

// iOS setup (one-time)
// $ npx react-native-notify-kit init-nse && cd ios && pod install

Full guide: docs/fcm-mode.md.

Backward compatibility

FCM Mode is opt-in. If you have an existing integration that calls displayNotification() manually from onMessage, it keeps working exactly the same after upgrading to 10.0.0. Migrate when you're ready, not because you have to.

Breaking changes

• react-native-notify-kit/package.json now declares an exports map. For backward compatibility, ./src/* and ./dist/* internal paths remain exposed but are deprecated and will be removed in a future major. Migrate to the public entries (react-native-notify-kit, react-native-notify-kit/server).

See the CHANGELOG for the full list.

Credits

To everyone who reacted 👍 on invertase/notifee#129, this release is for you.

Feedback

Try it out and let me know what breaks. Open an issue for bugs, reply here for design questions or use cases.

[mefjuu]

Great to hear that! Removing Android notification field in favor data-only notification and iOS APS 'alert' field composed on server were the only ways to achieve notifications delivery reliability, until now :)
As you wrote somewhere else - the default options still guarantee the same behavior as Notifee lib previously? (I mean juggling handlers between Notifee and firebase messaging to handle delivering regardless app state).

[marcocrupi]

Yes, nothing about the legacy path changes in 10.0.0. If you keep the manual displayNotification pattern (data-only + headless task on Android, silent push on iOS), it works identically after the upgrade. FCM Mode is purely additive and opt-in.

On the handler juggling: you still wire both setBackgroundMessageHandler and onMessage, that's RNFB's contract (RNFB picks which one fires based on app state, Notify Kit can't hide that). What changes is what goes inside each handler: one line, await notifee.handleFcmMessage(remoteMessage), and the platform/state asymmetry is handled internally:

• Android foreground/background/killed → displayNotification (headless task on killed).
• iOS foreground → in-app banner via displayNotification (or suppressed if you set ios.suppressForegroundBanner: true).
• iOS background/killed → intentional no-op; the NSE already drew the notification from the same notifee_options blob, so a second display would duplicate.

So yes, delivery-regardless-of-app-state still works, you just stop hand-rolling the payload shape and the iOS-vs-Android branching. And if a push arrives without notifee_options (e.g. legacy sender), the default fallbackBehavior: 'display' builds a minimal notification from remoteMessage.notification.title/body so nothing gets silently dropped.