/mobile-notifications-push

name: mobile-notifications-push
description: Push notification patterns - expo-notifications (Expo) and @react-native-firebase/messaging (bare RN), permission handling, token management, foreground/background/tap listeners, local scheduling, Android channels, notification categories and actions, badge management, rich notifications

Push Notification Patterns

> **Quick Guide:** Two main approaches: `expo-notifications` (Expo workflow, unified API for push + local) and `@react-native-firebase/messaging` (bare RN, FCM/APNs direct). Always request permissions before retrieving tokens. Handle three notification states: foreground (app open), background (app minimized), and quit (app killed). Set up Android notification channels before displaying any notification. Push notifications require a physical device -- they do not work on emulators or simulators.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST request notification permissions BEFORE retrieving push tokens -- calling getExpoPushTokenAsync or messaging().getToken() without permission will fail or return an unusable token)**

**(You MUST create an Android notification channel BEFORE displaying any notification on Android 8+ -- notifications without a channel are silently dropped)**

**(You MUST handle ALL three notification states: foreground (onMessage/addNotificationReceivedListener), background (setBackgroundMessageHandler/registerTaskAsync), and tap/response (addNotificationResponseReceivedListener/onNotificationOpenedApp + getInitialNotification))**

**(You MUST clean up notification listeners on unmount -- leaked listeners cause memory leaks and duplicate handlers)**

**(You MUST test push notifications on a physical device -- emulators and simulators do not support push tokens)**

</critical_requirements>

---

**Auto-detection:** expo-notifications, @react-native-firebase/messaging, push notification, push token, getExpoPushTokenAsync, getDevicePushTokenAsync, scheduleNotificationAsync, setNotificationHandler, addNotificationReceivedListener, addNotificationResponseReceivedListener, setBackgroundMessageHandler, onMessage, onNotificationOpenedApp, getInitialNotification, notification channel, setNotificationChannelAsync, notification category, notification actions, setBadgeCountAsync, FCM, APNs, remote notification, local notification, useLastNotificationResponse

**When to use:**

• Sending remote push notifications to users via FCM/APNs
• Requesting and managing notification permissions
• Retrieving and storing push tokens (Expo push token or native FCM/APNs token)
• Handling notification events in foreground, background, and quit states
• Scheduling local notifications (reminders, timers, recurring alerts)
• Creating Android notification channels with custom sound/vibration/importance
• Adding interactive notification actions (buttons, text input)
• Managing app icon badge counts
• Implementing notification tap navigation (deep linking from notifications)

**Key patterns covered:**

• Permission request flow with status checking
• Push token retrieval and refresh handling
• Foreground notification presentation (setNotificationHandler)
• Background message handling (headless JS tasks)
• Notification tap/response handling with navigation
• Local notification scheduling with trigger types
• Android notification channels and channel groups
• Notification categories with interactive actions
• Badge count management
• Rich notification content (images, sounds, data payloads)

**When NOT to use:**

• In-app messaging or toast/snackbar UI (those are UI components, not OS notifications)
• Email or SMS notifications (server-side concern)
• Web push notifications (different API entirely)

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Permission flow, token management, foreground/background/tap listeners, notification handler setup
• [examples/scheduling.md](examples/scheduling.md) - Local notification scheduling, trigger types, Android channels, categories and actions, badge management
• [reference.md](reference.md) - Decision frameworks, platform differences, checklists

---

<philosophy>

Philosophy

Push notifications bridge the gap between your app and users when the app is not in focus. The two main approaches in React Native serve different workflows:

**expo-notifications** provides a unified API for both push and local notifications, abstracts FCM/APNs differences, and integrates with Expo's push service for simplified server-side sending. Best for Expo-managed and bare workflows that want a single library for all notification needs.

**@react-native-firebase/messaging** provides direct FCM integration, pairs naturally with Firebase's backend services, and is the standard for bare React Native projects already using Firebase. For displaying foreground notifications with Firebase, pair it with a local notification display library.

**Core principles:**

1. **Permission first** -- Always check and request permissions before any token or notification work. Requesting at a contextually appropriate moment (after user sees value) dramatically improves grant rates. 2. **Handle all three states** -- Notifications arrive when the app is in foreground, background, or quit. Each state requires a different listener. Missing one means silently lost notifications. 3. **Channels are mandatory on Android** -- Android 8+ (API 26+) requires notification channels. Without one, notifications are silently dropped. Create channels at app startup, not at send time. 4. **Tokens change** -- Push tokens can rotate. Register a token refresh listener and update your backend whenever the token changes. 5. **Physical device required** -- Push notification infrastructure (FCM/APNs) does not work on emulators or simulators. Local notifications may work on simu