create-expo-boilerplate 1.1.2 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +38 -0
  2. package/dist/add.js +218 -0
  3. package/dist/generate.js +3 -1
  4. package/dist/index.js +35 -5
  5. package/dist/manifest.js +51 -0
  6. package/dist/modules/index.js +7 -0
  7. package/dist/modules/notifications.js +241 -0
  8. package/dist/modules/shared.js +67 -0
  9. package/dist/modules/subscriptions.js +223 -0
  10. package/dist/modules/types.js +57 -0
  11. package/dist/steps/format.js +11 -2
  12. package/dist/steps/javascript.js +14 -7
  13. package/dist/steps/readme.js +1 -0
  14. package/dist/steps/styling.js +1 -0
  15. package/dist/template.js +2 -0
  16. package/dist/versions.js +8 -0
  17. package/modules/notifications/files/plugins/withAndroidDefaultNotificationChannel.js +64 -0
  18. package/modules/notifications/files/src/notifications/NotificationProvider.tsx +309 -0
  19. package/modules/notifications/files/src/notifications/NotificationRoot.tsx +21 -0
  20. package/modules/notifications/files/src/notifications/README.md +763 -0
  21. package/modules/notifications/files/src/notifications/__tests__/NotificationProvider.test.tsx +358 -0
  22. package/modules/notifications/files/src/notifications/__tests__/pendingPress.test.ts +61 -0
  23. package/modules/notifications/files/src/notifications/__tests__/permissionState.test.ts +92 -0
  24. package/modules/notifications/files/src/notifications/__tests__/routing.test.ts +109 -0
  25. package/modules/notifications/files/src/notifications/__tests__/service.test.ts +189 -0
  26. package/modules/notifications/files/src/notifications/backgroundHandler.ts +158 -0
  27. package/modules/notifications/files/src/notifications/channels.ts +70 -0
  28. package/modules/notifications/files/src/notifications/components/NotificationPermissionBanner.tsx +134 -0
  29. package/modules/notifications/files/src/notifications/config.ts +179 -0
  30. package/modules/notifications/files/src/notifications/index.ts +90 -0
  31. package/modules/notifications/files/src/notifications/log.ts +57 -0
  32. package/modules/notifications/files/src/notifications/navigation.ts +11 -0
  33. package/modules/notifications/files/src/notifications/pendingPress.ts +86 -0
  34. package/modules/notifications/files/src/notifications/permissionState.ts +75 -0
  35. package/modules/notifications/files/src/notifications/routing.ts +99 -0
  36. package/modules/notifications/files/src/notifications/service.ts +476 -0
  37. package/modules/notifications/files/src/notifications/setup.ts +18 -0
  38. package/modules/notifications/files/src/notifications/types.ts +74 -0
  39. package/modules/notifications/files/src/notifications/useNotificationPermission.ts +80 -0
  40. package/modules/notifications/files/src/notifications/useNotificationSync.ts +71 -0
  41. package/modules/notifications/files/src/notifications/useNotifications.ts +13 -0
  42. package/modules/notifications/overlays/react-navigation/src/navigation/navigationRef.ts +6 -0
  43. package/modules/notifications/overlays/react-navigation/src/notifications/navigation.ts +38 -0
  44. package/modules/notifications/overlays/styling/stylesheet/src/notifications/components/NotificationPermissionBanner.tsx +134 -0
  45. package/modules/notifications/overlays/styling/tailwind/src/notifications/components/NotificationPermissionBanner.tsx +108 -0
  46. package/modules/notifications/translations/ar.json +12 -0
  47. package/modules/notifications/translations/en.json +12 -0
  48. package/modules/notifications/translations/es.json +12 -0
  49. package/modules/subscriptions/files/src/app/subscription.tsx +1 -0
  50. package/modules/subscriptions/files/src/subscription/README.md +215 -0
  51. package/modules/subscriptions/files/src/subscription/SubscriptionProvider.tsx +562 -0
  52. package/modules/subscriptions/files/src/subscription/SubscriptionRoot.tsx +30 -0
  53. package/modules/subscriptions/files/src/subscription/__tests__/SubscriptionProvider.test.tsx +931 -0
  54. package/modules/subscriptions/files/src/subscription/__tests__/UnlockModal.test.tsx +79 -0
  55. package/modules/subscriptions/files/src/subscription/__tests__/config.test.ts +23 -0
  56. package/modules/subscriptions/files/src/subscription/__tests__/introOffer.test.ts +93 -0
  57. package/modules/subscriptions/files/src/subscription/__tests__/offeringContent.test.ts +215 -0
  58. package/modules/subscriptions/files/src/subscription/__tests__/planChange.test.ts +356 -0
  59. package/modules/subscriptions/files/src/subscription/__tests__/purchaseErrors.test.ts +111 -0
  60. package/modules/subscriptions/files/src/subscription/__tests__/service.test.ts +369 -0
  61. package/modules/subscriptions/files/src/subscription/__tests__/statusNotice.test.ts +259 -0
  62. package/modules/subscriptions/files/src/subscription/__tests__/subscriptionState.test.ts +690 -0
  63. package/modules/subscriptions/files/src/subscription/components/CrossPlatformNotice.tsx +94 -0
  64. package/modules/subscriptions/files/src/subscription/components/PremiumGate.tsx +74 -0
  65. package/modules/subscriptions/files/src/subscription/components/SubscriptionStatusNotice.tsx +153 -0
  66. package/modules/subscriptions/files/src/subscription/components/UnlockModal.tsx +223 -0
  67. package/modules/subscriptions/files/src/subscription/config.ts +54 -0
  68. package/modules/subscriptions/files/src/subscription/index.ts +95 -0
  69. package/modules/subscriptions/files/src/subscription/introOffer.ts +61 -0
  70. package/modules/subscriptions/files/src/subscription/management.ts +30 -0
  71. package/modules/subscriptions/files/src/subscription/navigation.ts +15 -0
  72. package/modules/subscriptions/files/src/subscription/offeringContent.ts +259 -0
  73. package/modules/subscriptions/files/src/subscription/planChange.ts +219 -0
  74. package/modules/subscriptions/files/src/subscription/purchaseErrors.ts +140 -0
  75. package/modules/subscriptions/files/src/subscription/screens/PaywallScreen.tsx +466 -0
  76. package/modules/subscriptions/files/src/subscription/service.ts +270 -0
  77. package/modules/subscriptions/files/src/subscription/statusNotice.ts +189 -0
  78. package/modules/subscriptions/files/src/subscription/subscriptionState.ts +485 -0
  79. package/modules/subscriptions/files/src/subscription/types.ts +164 -0
  80. package/modules/subscriptions/files/src/subscription/useSubscriptionUser.ts +29 -0
  81. package/modules/subscriptions/overlays/react-navigation/src/navigation/navigationRef.ts +6 -0
  82. package/modules/subscriptions/overlays/react-navigation/src/subscription/navigation.ts +14 -0
  83. package/modules/subscriptions/overlays/styling/stylesheet/src/subscription/components/CrossPlatformNotice.tsx +94 -0
  84. package/modules/subscriptions/overlays/styling/stylesheet/src/subscription/components/SubscriptionStatusNotice.tsx +153 -0
  85. package/modules/subscriptions/overlays/styling/stylesheet/src/subscription/components/UnlockModal.tsx +227 -0
  86. package/modules/subscriptions/overlays/styling/stylesheet/src/subscription/screens/PaywallScreen.tsx +467 -0
  87. package/modules/subscriptions/overlays/styling/tailwind/src/subscription/components/CrossPlatformNotice.tsx +74 -0
  88. package/modules/subscriptions/overlays/styling/tailwind/src/subscription/components/SubscriptionStatusNotice.tsx +136 -0
  89. package/modules/subscriptions/overlays/styling/tailwind/src/subscription/components/UnlockModal.tsx +181 -0
  90. package/modules/subscriptions/overlays/styling/tailwind/src/subscription/screens/PaywallScreen.tsx +364 -0
  91. package/modules/subscriptions/translations/ar.json +128 -0
  92. package/modules/subscriptions/translations/en.json +112 -0
  93. package/modules/subscriptions/translations/es.json +112 -0
  94. package/package.json +3 -2
  95. package/template/jest.config.js +3 -1
  96. package/template/jest.setup.ts +36 -10
  97. package/template/src/localization/__tests__/i18n.test.ts +25 -0
  98. package/template/src/services/client.ts +14 -5
  99. package/template/src/shared/components/__tests__/Button.test.tsx +24 -0
@@ -0,0 +1,763 @@
1
+ # Notifications Module
2
+
3
+ > **Plug-and-play push notification layer for React Native / Expo.**
4
+ > Permissions, Android heads-up channels, remote push in foreground / background / killed states, tap routing, and local trigger scheduling — behind one import path, with two integration points and one file to configure.
5
+
6
+ **Transport only.** This module _moves_ notifications. It contains no features and knows nothing about what any given notification means. Nothing in it names a product concept: the parts you edit are `config.ts` and the token adapter, `useNotificationSync.ts`.
7
+
8
+ Generated by `create-expo-boilerplate add notifications`.
9
+
10
+ ---
11
+
12
+ ## Table of Contents
13
+
14
+ 1. [Quick start](#quick-start)
15
+ 2. [Scope — what this owns and what it does not](#scope--what-this-owns-and-what-it-does-not)
16
+ 3. [Architecture](#architecture)
17
+ 4. [Native setup](#native-setup)
18
+ 5. [Integration points](#integration-points)
19
+ 6. [Configuration reference](#configuration-reference)
20
+ 7. [Public API](#public-api)
21
+ 8. [Permission policy](#permission-policy)
22
+ 9. [Delivery matrix](#delivery-matrix)
23
+ 10. [Heads-up](#heads-up)
24
+ 11. [Local scheduling](#local-scheduling)
25
+ 12. [App icon badge](#app-icon-badge)
26
+ 13. [Backend contract](#backend-contract)
27
+ 14. [The Android duplicate-notification trap](#the-android-duplicate-notification-trap)
28
+ 15. [Gotchas that will cost you an afternoon](#gotchas-that-will-cost-you-an-afternoon)
29
+ 16. [Testing & debugging](#testing--debugging)
30
+ 17. [Known limits](#known-limits)
31
+ 18. [Switching to FCM Mode](#switching-to-fcm-mode)
32
+ 19. [Replacing the stack](#replacing-the-stack)
33
+ 20. [Verification & troubleshooting](#verification--troubleshooting)
34
+
35
+ ---
36
+
37
+ ## Quick start
38
+
39
+ `create-expo-boilerplate add notifications` already did the wiring:
40
+
41
+ | What | Where |
42
+ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
43
+ | The module | `src/notifications/` |
44
+ | Dependencies | `@react-native-firebase/app`, `@react-native-firebase/messaging`, `react-native-notify-kit` in `package.json` |
45
+ | Config plugins, APNs entitlement, background mode, Firebase file paths, dynamic frameworks | `app.config.ts` |
46
+ | Android default-channel plugin | `plugins/withAndroidDefaultNotificationChannel.js` |
47
+ | Background handlers + channel creation | `import '@/notifications/setup'` in the entry file |
48
+ | Provider | `<NotificationRoot>` in `src/providers/AppProviders.tsx` |
49
+ | Permission banner | Settings screen (unless you passed `--no-banner`) |
50
+ | Copy | `notifications.permission.*` in every `src/localization/translations/*.json` |
51
+ | Test mocks | `jest.setup.ts` |
52
+
53
+ What is left for you:
54
+
55
+ | # | Step | Where |
56
+ | --- | ----------------------------------------------------- | ------------------------------------------------------------------------------------- |
57
+ | 1 | Add the Firebase files (if you skipped the prompt) | `firebase/google-services.json`, `firebase/GoogleService-Info.plist` |
58
+ | 2 | Upload your APNs `.p8` key | Firebase console → Project settings → Cloud Messaging |
59
+ | 3 | Rebuild the dev client — these are new native modules | `npx expo prebuild --clean`, then `yarn ios:development` / `yarn android:development` |
60
+ | 4 | ⚙ Point the token call at your backend | `useNotificationSync.ts` |
61
+ | 5 | ⚙ Your payload vocabulary, channels and routes | `config.ts` |
62
+
63
+ Steps 4 and 5 are the only module files you edit. Nothing else in this folder names a channel, a payload type, a route, or a product feature.
64
+
65
+ ---
66
+
67
+ ## Scope — what this owns and what it does not
68
+
69
+ | Concern | Owner |
70
+ | ------------------------------------------------------ | ------------------------------------------------------------ |
71
+ | Asking for permission, and reading the real state back | **this module** |
72
+ | Creating and versioning Android channels | **this module** |
73
+ | Acquiring the FCM token and handing it to your backend | **this module** |
74
+ | Receiving remote messages in every app state | **this module** |
75
+ | Turning a payload into an allowlisted route | **this module** |
76
+ | Handing local triggers to the OS | **this module** |
77
+ | Deciding **what** to notify about, and **when** | **your feature code** |
78
+ | Firing a recurring notification on a schedule | **your backend** (see [Backend contract](#backend-contract)) |
79
+
80
+ The last two rows are the boundary that keeps this portable. A feature that needs local notifications builds its own triggers and calls `scheduleLocalNotifications` — the module takes fully-resolved instants and has no opinion on how they were derived.
81
+
82
+ **The dependency arrow points one way.** Feature code imports `@/notifications`; nothing here imports feature code. If you ever need an import pointing outward from this folder, something has been put on the wrong side of the line.
83
+
84
+ ---
85
+
86
+ ## Architecture
87
+
88
+ ```
89
+ ┌──────────────────────────────────────────────────────────┐
90
+ │ Host App │
91
+ │ │
92
+ │ index.ts │
93
+ │ ┌────────────────────────────────────────────┐ │
94
+ │ │ import '@/notifications/setup' │ ← module │
95
+ │ └────────────────────────────────────────────┘ scope │
96
+ │ │
97
+ │ src/providers/AppProviders.tsx │
98
+ │ ┌────────────────────────────────────────────┐ │
99
+ │ │ <NotificationRoot> │ │
100
+ │ │ → <NotificationProvider │ │
101
+ │ │ isLoggedIn={useIsLoggedIn()} │ │
102
+ │ │ onNavigate={navigate…}> │ │
103
+ │ └────────────────────────────────────────────┘ │
104
+ │ │
105
+ │ ONE permission screen │
106
+ │ ┌────────────────────────────────────────────┐ │
107
+ │ │ <NotificationPermissionBanner /> │ │
108
+ │ └────────────────────────────────────────────┘ │
109
+ └──────────────────────────────────────────────────────────┘
110
+ │
111
+ ┌───────────────▼──────────────────┐
112
+ │ NotificationProvider │
113
+ │ • every listener, once │
114
+ │ • cold-start route queue │
115
+ │ • token registration │
116
+ │ • NEVER prompts │
117
+ └───────────────┬──────────────────┘
118
+ │
119
+ ┌───────────────▼──────────────────┐
120
+ │ permissionState / routing │
121
+ │ (PURE, tested) │
122
+ └───────────────┬──────────────────┘
123
+ │
124
+ ┌───────────────▼──────────────────┐
125
+ │ service.ts │
126
+ │ the ONLY file importing │
127
+ │ notify-kit + firebase/messaging │
128
+ └───────────────┬──────────────────┘
129
+ │
130
+ NotifyKit (draws, schedules)
131
+ Firebase Messaging (delivers)
132
+ ```
133
+
134
+ **The stack.** `@react-native-firebase/messaging` receives messages but draws nothing — no channels, no foreground presentation, no local scheduling. `react-native-notify-kit` supplies all of that. Both are needed; neither is sufficient.
135
+
136
+ Why this pairing rather than `expo-notifications`: on iOS `expo-notifications` yields an **APNs** token, and FCM cannot send to an APNs token. Using it would force the backend to add a separate direct-APNs sender. This stack keeps one FCM token on both platforms and leaves the existing Firebase send path untouched. The trade-off — NotifyKit is a community fork of the archived Notifee — is addressed in [Replacing the stack](#replacing-the-stack).
137
+
138
+ ### File structure
139
+
140
+ | File | Role |
141
+ | --------------------------------------------- | -------------------------------------------------------------------------------- |
142
+ | `index.ts` | Public API. The only path app code imports from. |
143
+ | **`config.ts`** | ⚙ **Every project-specific value.** Vocabulary, channels, routes, strategy. |
144
+ | `types.ts` | Shared types: the five-state permission union, `LocalTrigger`. |
145
+ | `service.ts` | The single SDK boundary. No React, no state. |
146
+ | `channels.ts` | Android channel creation + mute detection. |
147
+ | `permissionState.ts` | **Pure.** Raw OS status → banner state. |
148
+ | `routing.ts` | **Pure.** Payload → allowlisted route. |
149
+ | `setup.ts` | Entry-file side effects: registers the background handlers, creates channels. |
150
+ | `backgroundHandler.ts` | Module-scope background/killed handlers, and the iOS remote-tap hand-back. |
151
+ | `pendingPress.ts` | Parks a background press until the navigator exists. |
152
+ | `log.ts` | Dev-only tracing for payloads and remote messages. |
153
+ | `NotificationProvider.tsx` | Listeners, cold-start queue, token sync. |
154
+ | `NotificationRoot.tsx` | The provider wired to this app's session and navigator. |
155
+ | `navigation.ts` | Opens a resolved route with this app's router (Expo Router or React Navigation). |
156
+ | `useNotifications.ts` | Context hook. |
157
+ | `useNotificationPermission.ts` | Screen-level hook — the only route to the OS prompt. |
158
+ | **`useNotificationSync.ts`** | ⚙ **Host adapter.** Your backend's token endpoint. |
159
+ | `components/NotificationPermissionBanner.tsx` | The warning banner. |
160
+
161
+ ---
162
+
163
+ ## Native setup
164
+
165
+ > The generator applied everything in this section. It is documented so you know what each piece is for, and what to check when something silently fails.
166
+
167
+ ### Dependencies
168
+
169
+ ```bash
170
+ yarn add @react-native-firebase/app @react-native-firebase/messaging react-native-notify-kit
171
+ ```
172
+
173
+ ### `app.config.ts`
174
+
175
+ ```ts
176
+ plugins: [
177
+ '@react-native-firebase/app',
178
+ '@react-native-firebase/messaging',
179
+ 'react-native-notify-kit',
180
+ './plugins/withAndroidDefaultNotificationChannel',
181
+ ];
182
+ ```
183
+
184
+ Drop `google-services.json` and `GoogleService-Info.plist` in, and upload the APNs `.p8` key to **Firebase console → Project settings → Cloud Messaging** so FCM can relay to iOS.
185
+
186
+ **iOS also needs this in `app.config.ts`, and no plugin adds it for you:**
187
+
188
+ ```ts
189
+ ios: {
190
+ entitlements: { 'aps-environment': 'development' },
191
+ infoPlist: { UIBackgroundModes: ['remote-notification', /* … */] },
192
+ }
193
+ ```
194
+
195
+ This is the easiest thing in the whole setup to miss, because nothing fails loudly. The `@react-native-firebase/messaging` config plugin is **Android-only** — its source contains a bare `// iOS` comment with no mods beneath it — and NotifyKit's iOS plugin only builds the opt-in Notification Service Extension. Neither touches entitlements.
196
+
197
+ Without `aps-environment` the app cannot register with APNs, so `getToken()` returns `null`, no token is ever sent to the backend, and every iOS push is dropped with nothing in the logs to say why.
198
+
199
+ `development` is correct even for App Store builds — Xcode rewrites it to `production` when it archives a release, and hardcoding `production` breaks push on debug builds.
200
+
201
+ Two things this does _not_ do: it does not enable the capability on the Apple Developer portal (EAS handles that during credentials setup, or tick it on the App ID by hand), and it does not survive being added by hand in Xcode — `ios/` is gitignored in a CNG project, so a manual capability toggle is wiped by the next `expo prebuild`. It has to live in `app.config.ts`.
202
+
203
+ Verify without regenerating the native project:
204
+
205
+ ```bash
206
+ npx expo config --type prebuild --json | jq '.ios.entitlements, .ios.infoPlist.UIBackgroundModes'
207
+ ```
208
+
209
+ `POST_NOTIFICATIONS` (Android 13+) is added by the NotifyKit plugin. It deliberately does **not** add `SCHEDULE_EXACT_ALARM` or `USE_FULL_SCREEN_INTENT` — leave both off; see [Known limits](#known-limits) and [Gotcha 3](#3-exact-alarms-will-be-refused-and-the-throw-disappears).
210
+
211
+ The second plugin, `withAndroidDefaultNotificationChannel`, is **not optional** — without its `tools:replace` the Android build fails outright. See [Gotcha 4](#4-the-manifest-meta-data-collides-with-rnfirebase).
212
+
213
+ ---
214
+
215
+ ## Integration points
216
+
217
+ There are two, plus the banner.
218
+
219
+ ### 1. Entry point — `index.ts`
220
+
221
+ ```ts
222
+ import '@/notifications/setup'; // side effect — MUST be module scope
223
+ ```
224
+
225
+ `setup.ts` registers the background handlers and creates the channels.
226
+
227
+ A background message spins up the JS runtime **headless**, with no component tree. A handler registered inside a React component is attached too late by definition.
228
+
229
+ On Android 13+ the OS **refuses to show the notification prompt until the app has at least one channel**, so a permission request that beats channel creation silently resolves as denied with no dialog. That bug presents as "permissions are broken", not as "channels are missing" — which is why channels are created at the entry rather than lazily.
230
+
231
+ ### 2. Providers — `src/providers/AppProviders.tsx`
232
+
233
+ ```tsx
234
+ <APIProvider>
235
+ <NotificationRoot>{children}</NotificationRoot>
236
+ </APIProvider>
237
+ ```
238
+
239
+ `NotificationRoot` reads the session from `useIsLoggedIn()` and navigates through `navigation.ts`. It sits inside `APIProvider` because token registration is a mutation, and around the navigation root so the navigator exists by the time a queued cold-start route is delivered.
240
+
241
+ ### 3. The permission screen
242
+
243
+ ```tsx
244
+ <NotificationPermissionBanner />
245
+ ```
246
+
247
+ Mount it on whichever screen is allowed to ask, always tied to an explicit user action. Which channel its `channel-blocked` state checks, and which channel Settings deep-links to, is `PRIMARY_CHANNEL_ID` in `config.ts`.
248
+
249
+ ---
250
+
251
+ ## Configuration reference
252
+
253
+ Everything project-specific lives in `config.ts`. Nothing outside it names a channel, a payload type, or a route.
254
+
255
+ | Constant | What it decides |
256
+ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
257
+ | `NOTIFICATION_TYPES` | The payload vocabulary. `NotificationType` is derived from it, so adding a type is one edit. |
258
+ | `CHANNELS` / `CHANNEL_IDS` | Android channels, their importance, sound and vibration. |
259
+ | `DEFAULT_CHANNEL_ID` | Fallback when a payload carries no `channel_id`. **Must match the manifest plugin.** |
260
+ | `PRIMARY_CHANNEL_ID` | The channel whose mute state raises `channel-blocked`, and where Settings deep-links. |
261
+ | `DEPRECATED_CHANNEL_IDS` | Retired channel ids, deleted at startup after a version bump. |
262
+ | `ROUTE_BY_TYPE` | `type` → in-app route. `null` means "just open the app". Paths work with both Expo Router and React Navigation (resolved through `src/navigation/linking.ts`). |
263
+ | `TYPES_WITH_ID` | Types whose payload `id` is appended to the route as `?id=…`. |
264
+ | `TYPE_BY_PAYLOAD_VALUE` | Backend wire value → internal type. Matched case-insensitively. |
265
+ | `AUTHENTICATED_ROUTES` | Routes dropped when logged out, so a cold start does not flash a gated screen. |
266
+ | `CLEAR_BADGE_ON_OPEN` | Clear the app icon badge when the app opens or returns to the front. See [App icon badge](#app-icon-badge). |
267
+ | `ANDROID_DISPLAY_STRATEGY` | `fcm-draws` (default) or `app-draws`. See [FCM Mode](#switching-to-fcm-mode). |
268
+
269
+ ### Channel ids carry a version suffix, and it is not decoration
270
+
271
+ Once a channel exists on a device, Android freezes everything about it except the name and description — importance, sound and vibration cannot be changed for as long as the app stays installed. To change a frozen property: bump the suffix (`general.v1` → `general.v2`), add the old id to `DEPRECATED_CHANNEL_IDS`, and update the backend's `channel_id`. This resets any per-channel preference the user had set, so do it deliberately rather than routinely.
272
+
273
+ ---
274
+
275
+ ## Public API
276
+
277
+ ```ts
278
+ import {
279
+ NotificationProvider,
280
+ NotificationPermissionBanner,
281
+ useNotifications,
282
+ useNotificationPermission,
283
+ useNotificationSync,
284
+ configureNotifications,
285
+ scheduleLocalNotifications,
286
+ cancelLocalNotifications,
287
+ } from '@/notifications';
288
+ ```
289
+
290
+ ```ts
291
+ const { permission, fcmToken, refreshPermission, requestPermission, openSettings } =
292
+ useNotifications();
293
+
294
+ const { state, isEnabled, canPrompt, requestOrOpenSettings, refresh } = useNotificationPermission();
295
+ ```
296
+
297
+ ---
298
+
299
+ ## Permission policy
300
+
301
+ **`NotificationProvider` never prompts.** It reads permission and exposes a request function, but the only consumer of that function is `useNotificationPermission`. Mounting that hook is what makes a screen able to prompt — which keeps "never on mount, only on a tap" a structural property rather than a convention someone breaks in six months.
302
+
303
+ Out of the box one screen mounts it, through `NotificationPermissionBanner`: Settings. The banner is the only thing that prompts, and only on a deliberate tap of its CTA. Adding another screen is a decision, not a detail — the iOS prompt is spent permanently on the first refusal.
304
+
305
+ If you add in-app notification preferences (a switch for "marketing", a reminders toggle), keep them separate from the device grant: the switch holds the account's preference, the banner reports whether the OS will deliver at all.
306
+
307
+ The prompt is spent on an explicit user action, never on mount. A prompt the user did not ask for is the one they deny, and on iOS a denial is permanent.
308
+
309
+ ### The five states
310
+
311
+ | State | Meaning | CTA |
312
+ | ----------------- | ---------------------------------------------------------------- | --------------------- |
313
+ | `granted` | Delivering. | _(banner hidden)_ |
314
+ | `undetermined` | Never asked. | Prompt |
315
+ | `denied` | Refused, prompt still reachable (Android, before 2nd refusal). | Prompt |
316
+ | `blocked` | Refused, **prompt gone forever**. | Open Settings |
317
+ | `channel-blocked` | **Android.** App permission granted, `PRIMARY_CHANNEL_ID` muted. | Open channel settings |
318
+
319
+ The last two are why the union exists rather than a boolean:
320
+
321
+ - **`blocked`** — `requestPermission()` is a no-op once iOS has recorded a denial. A CTA that calls it renders a button that does nothing, which reads as a broken app rather than a reversible setting.
322
+ - **`channel-blocked`** — every permission API reports success and Android drops every notification on that channel anyway. Nothing surfaces it except an explicit `isChannelBlocked()` check.
323
+
324
+ Status is re-read on `AppState → active` **and** on screen focus, which is what closes the loop when someone leaves for Settings, flips the switch, and comes back.
325
+
326
+ ---
327
+
328
+ ## Delivery matrix
329
+
330
+ | App state | What the OS does | What the module does |
331
+ | -------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
332
+ | **Foreground** | Nothing is drawn, either platform. FCM hands the message to JS and stops. | `onMessage()` → `displayNotification()`. **Without this a foreground push is invisible.** |
333
+ | **Background** | System tray, drawn by FCM from the `notification` block. | `onNotificationOpenedApp()` for the tap. Background handler for data only. |
334
+ | **Killed** | Delivered only if the payload has a display block. | `getInitialNotification()` on boot → queued until the router is ready. |
335
+
336
+ ### Remote flow, by app state
337
+
338
+ ```
339
+ backend ──► FCM ──► device
340
+ │
341
+ ┌───────────────┼────────────────────┐
342
+ FOREGROUND BACKGROUND KILLED
343
+ │ │ │
344
+ onMessage() FCM draws tray FCM draws tray
345
+ │ from `notification` from `notification`
346
+ ▼ │ │ ⚠ data-only DROPPED
347
+ notifee.displayNotification │
348
+ │ │ │
349
+ ▼ ▼ ▼
350
+ tap tap tap → cold launch
351
+ │ │ │
352
+ onForegroundEvent onNotificationOpenedApp getInitialNotification()
353
+ │ │ │ parked until router ready
354
+ └───────────────┴────────────────────┘
355
+ ▼
356
+ routing.ts allowlist → router.push
357
+ ```
358
+
359
+ Nothing in the foreground column is free: **FCM draws nothing while the app is open**, on either platform. The `displayNotification` call is the only reason a foreground push is visible.
360
+
361
+ ### iOS: who owns the tap
362
+
363
+ On iOS both NotifyKit and React Native Firebase Messaging want to be
364
+ `UNUserNotificationCenter.delegate`, and NotifyKit wins — it re-chains itself in
365
+ on every `didBecomeActive`, while Firebase installs itself once at launch.
366
+
367
+ With NotifyKit's `handleRemoteNotifications` left at its default of `true`, it
368
+ then **claims** an FCM tap rather than passing it down the chain whenever it has
369
+ nothing below it to pass to. Firebase never hears about the notification, so
370
+ `onNotificationOpenedApp()` and `getInitialNotification()` both stay silent —
371
+ and NotifyKit's own `getInitialNotification()` returns `null` for it too,
372
+ because the payload carries no NotifyKit-authored id for its native store to
373
+ release. The push opens the app and lands nowhere, in **both** background and
374
+ killed states. Android has no delegate chain and is unaffected, which is exactly
375
+ how this presents in QA: "works on Android, does nothing on iOS".
376
+
377
+ `backgroundHandler.ts` sets `handleRemoteNotifications: false` at module scope —
378
+ the earliest JS in the app — so remote push has one owner on iOS (Firebase) and
379
+ local triggers keep theirs (NotifyKit).
380
+
381
+ ### NotifyKit's two press channels both land too early
382
+
383
+ NotifyKit splits presses across a foreground and a background channel by the app
384
+ state at the instant it hands the event to JS. Both instants fall **before**
385
+ `NotificationProvider` exists, for two different reasons:
386
+
387
+ - **App backgrounded.** iOS delivers the response while the app is still
388
+ `Inactive` — including the tap that brings a backgrounded app forward — so the
389
+ press goes to the _background_ channel. The app is never relaunched, and
390
+ `getInitialPayload()` already ran this launch.
391
+ - **App killed.** iOS delivers the response before the bundle has loaded, so
392
+ NotifyKit buffers the event natively. When the first JS listener attaches and
393
+ the buffer flushes, NotifyKit **re-reads the app state as it flushes** — the
394
+ app is `Active` by then, drawing the splash, so a press queued from a _killed_
395
+ app comes out on the _foreground_ channel.
396
+
397
+ The second one is the trap. A foreground subscription made from the provider is
398
+ attached several seconds after that flush — behind storage, i18n and the rest of
399
+ `useAppBootstrap` — so it misses the launch it exists for, and the press is dropped
400
+ with nothing listening.
401
+
402
+ `backgroundHandler.ts` therefore subscribes to **both** channels at module
403
+ scope, being the first app code in the bundle, and funnels every press into
404
+ `pendingPress.ts`. That parks the payload until `onNotificationPress` drains it
405
+ for the provider. Since one tap can now arrive by two paths depending on who
406
+ owned the notification natively, the provider ignores a repeat of the same route
407
+ within a two-second window.
408
+
409
+ ### One library must not be able to hang the other
410
+
411
+ NotifyKit's iOS `getInitialNotification()` only releases its stored notification
412
+ once a native `didFinishLaunching` observer has marked it _gathered_; until then
413
+ it parks the promise's resolver and returns nothing — and if that observer never
414
+ runs, the promise **never settles**. Awaited in sequence ahead of Firebase, that
415
+ alone kills cold-start routing for remote pushes as well.
416
+
417
+ `getInitialPayload()` reads both sources in parallel and puts a 2s timeout on the
418
+ NotifyKit half. The stores are one-shot and independent, so reading both costs
419
+ nothing and only one of them ever holds the tap.
420
+
421
+ ### Cold-start routing needs a queue
422
+
423
+ A tap on a killed app resolves its payload during the first render pass — long before storage, i18n, the splash, and route guards have settled. Pushing immediately either throws or lands on a guarded route that bounces the user straight back off.
424
+
425
+ `NotificationProvider` parks the route in a ref and flushes it once the navigator exists. If the target is gated and the user is not signed in, it is **dropped rather than queued** — it will not become deliverable this launch, and holding it would fire it the moment they signed in for an unrelated reason.
426
+
427
+ ---
428
+
429
+ ## Heads-up
430
+
431
+ Both halves are required. Neither alone is sufficient.
432
+
433
+ | | Requirement | Set in |
434
+ | ------- | -------------------------------------------------- | ------------ |
435
+ | Android | Channel `importance: HIGH` | `config.ts` |
436
+ | Android | Message `priority: "high"` + matching `channel_id` | Backend |
437
+ | iOS | `apns-priority: 10`, `apns-push-type: alert` | Backend |
438
+ | iOS | `foregroundPresentationOptions: { banner, list }` | `service.ts` |
439
+
440
+ If the backend cannot send `channel_id`, `plugins/withAndroidDefaultNotificationChannel` writes a manifest fallback. **Its `CHANNEL_ID` must match `DEFAULT_CHANNEL_ID` in `config.ts`** — if they drift, Android invents a low-importance "Miscellaneous" channel and every remote notification silently loses heads-up, with nothing in the logs.
441
+
442
+ ---
443
+
444
+ ## Local scheduling
445
+
446
+ A general capability of the module, available to any feature that needs the **device** to fire something without a network round trip.
447
+
448
+ ```ts
449
+ await scheduleLocalNotifications(triggers, {
450
+ channelId: 'general.v1',
451
+ cancelPrefix: 'digest-',
452
+ data: { type: 'general' },
453
+ });
454
+ ```
455
+
456
+ `scheduleLocalNotifications` clears every trigger matching `cancelPrefix`, then schedules the ones you hand it. Prefix-matched rather than `cancelAllNotifications`, so one feature's re-sync cannot wipe another's — give each feature its own prefix, and include the separator (`'digest-'`, not `'digest'`) or the match will also claim ids like `digestive-3`.
457
+
458
+ Passing an **empty array cancels everything under the prefix and schedules nothing**, which is what lets an on/off toggle behave as a delete with no second code path.
459
+
460
+ A `LocalTrigger` is domain-free: an id, an epoch-ms timestamp, a title and a body. Working out _which_ instants to fire at is your feature's job — the module has no notion of weekdays, wall-clock strings, or recurrence rules beyond the weekly repeat it hands the OS.
461
+
462
+ ```ts
463
+ interface LocalTrigger {
464
+ id: string; // must start with your cancelPrefix
465
+ timestamp: number; // epoch ms of the first occurrence
466
+ title: string;
467
+ body: string;
468
+ }
469
+ ```
470
+
471
+ ### When to reach for this, and when not to
472
+
473
+ Local scheduling **works offline**, has no timezone problem — the device already knows where it is — and needs no token, no registration round trip, and no server-side fan-out job.
474
+
475
+ What it costs:
476
+
477
+ - **Delivery is inexact on Android** — measured ~69s late, see [Known limits](#known-limits).
478
+ - **Changes need an app open.** A schedule edited server-side does not reach a device until that device next launches and re-syncs.
479
+ - **No server-side visibility.** Nobody can tell whether anything was actually delivered.
480
+
481
+ For anything recurring that the product cares about — a daily nudge, a streak reminder, a digest — those three costs usually push the decision to **remote push fired by the backend** instead. That is usually the better arrangement; see [Backend contract](#backend-contract).
482
+
483
+ ---
484
+
485
+ ## App icon badge
486
+
487
+ By default the badge is cleared whenever the app opens or comes back to the front (`CLEAR_BADGE_ON_OPEN` in `config.ts`) — opening the app means the user has seen what was waiting.
488
+
489
+ When the badge is a real count (unread messages, pending tasks), turn that off and keep the number in sync yourself:
490
+
491
+ ```ts
492
+ import { setBadgeCount } from '@/notifications';
493
+
494
+ setBadgeCount(unreadCount); // wherever the count changes
495
+ ```
496
+
497
+ and have the backend send the same number in remote pushes, so it is right while the app is closed:
498
+
499
+ ```jsonc
500
+ "apns": { "payload": { "aps": { "badge": 3 } } }
501
+ ```
502
+
503
+ | Platform | What the badge is |
504
+ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
505
+ | iOS | Exactly the number you set (or `aps.badge`). `0` hides it. |
506
+ | Android | Launcher-dependent. Most show a dot per notification on their own; numeric badges only on launchers that support them. |
507
+
508
+ `setBadgeCount`, `getBadgeCount` and `clearBadge` never throw — a badge is decoration.
509
+
510
+ ---
511
+
512
+ ## Backend contract
513
+
514
+ **One send path.** Firebase Admin SDK, FCM registration tokens, both platforms, iOS via Firebase's APNs relay.
515
+
516
+ ### Token registration
517
+
518
+ ```jsonc
519
+ // POST <your --token-endpoint> (Authorization: Bearer <access token>)
520
+ { "token": "fMEr...", "platform": "ios" }
521
+ ```
522
+
523
+ An FCM registration token on **both** platforms — iOS included, because Firebase relays to APNs on the backend's behalf. That is what lets the server keep one send path and one credential set.
524
+
525
+ The backend keys the token off the bearer token's user. Change the body in `useNotificationSync.ts` if your API expects a different shape. The request is sent with `silent: true`, so a failure never shows the user an error toast.
526
+
527
+ **There is no revoke call.** The backend should clear the token as part of its logout endpoint, so signing out is what stops delivery. The client also does _not_ delete the local FCM token — deleting it would force FCM to mint a fresh one on next sign-in for no benefit, since the backend has already detached the old one, and re-registering the same token against the new user is both correct and cheaper.
528
+
529
+ Called on login, on token refresh, and when permission transitions to granted — never at startup. A token acquired before the user agrees is one the backend will send to and the OS will silently discard, which presents as a broken backend rather than a missing permission.
530
+
531
+ ### Payload
532
+
533
+ ```jsonc
534
+ {
535
+ "message": {
536
+ "token": "...",
537
+ "notification": { "title": "New sign-in", "body": "Your account was used on a new device." },
538
+ "data": { "notification_type": "ACCOUNT_ALERT", "id": "482" }, // strings only
539
+ "android": {
540
+ "priority": "high",
541
+ "notification": { "channel_id": "general.v1" },
542
+ },
543
+ "apns": {
544
+ "headers": { "apns-priority": "10", "apns-push-type": "alert" },
545
+ "payload": { "aps": { "sound": "default" } },
546
+ },
547
+ },
548
+ }
549
+ ```
550
+
551
+ > **Killed-state rule.** Any push that must survive a force-quit app needs a **display block** — `notification` on FCM, `aps.alert` on APNs. Android drops data-only messages to a killed app entirely: nothing displays and no code runs. Put routing info in `data` _alongside_ it, never instead of it.
552
+
553
+ `data.route` is **ignored by design**. Routes come from the client's `ROUTE_BY_TYPE` allowlist, so a malformed or hostile payload can at worst open the app rather than deep-link anywhere it likes.
554
+
555
+ ### Recurring and scheduled pushes are the backend's job
556
+
557
+ Anything that fires on a schedule — a daily reminder, a weekly digest, a streak nudge — is sent by the backend as an ordinary remote push. **The device schedules nothing for it and stores no copy of the schedule.** The client is a rendering and routing layer; every decision about _whether_ and _when_ lives server-side.
558
+
559
+ | Question | Owner |
560
+ | --------------------------------------------- | -------------------------------------- |
561
+ | What the schedule **is** — time, days, on/off | **Backend** |
562
+ | **When** it fires | **Backend** — the scheduler |
563
+ | Which **timezone** that means | **Backend** |
564
+ | Which **screen** a tap opens | **Client** — `ROUTE_BY_TYPE` allowlist |
565
+
566
+ What a scheduler has to get right:
567
+
568
+ 1. **Know each user's timezone** (IANA, e.g. `Asia/Kolkata`). A stored time like `"7:25 pm"` is a bare wall clock with no zone attached — without the zone, it fires at 7:25 pm _somewhere else_. Either add a `timezone` field to the token endpoint or source it from the user profile; this is the single most common reason a scheduled push lands at the wrong hour.
569
+ 2. **Scan on a cadence.** Minute-granularity times mean the job runs at least once a minute, or buckets by minute and runs per bucket.
570
+ 3. **Match in the user's local time**, not the server's:
571
+
572
+ ```
573
+ for each active schedule:
574
+ tz := that user's timezone
575
+ local := now() in tz
576
+ if weekday(local) ∈ schedule.days
577
+ and hh:mm(local) == schedule.time:
578
+ send to every device token for that user
579
+ ```
580
+
581
+ 4. **Fan out to all of a user's devices.** One person, several handsets — each needs its own send.
582
+ 5. **De-duplicate.** Record `(schedule_id, local_date)` after sending. Without it, an overlapping or retried cron run sends the same push twice.
583
+ 6. **Handle DST.** A 2:30 am schedule does not exist on a spring-forward date and happens twice on a fall-back date. Pick a rule — skip and log, or fire once — rather than letting the library decide silently.
584
+ 7. **Send an explicit `channel_id`.** Without it Android falls back to the manifest default, and the user loses the ability to mute one category separately from another.
585
+
586
+ ---
587
+
588
+ ## The Android duplicate-notification trap
589
+
590
+ Under the default `ANDROID_DISPLAY_STRATEGY = 'fcm-draws'`, FCM has **already drawn** the tray notification by the time `setBackgroundMessageHandler` runs. Calling `displayNotification()` or `handleFcmMessage()` there draws a **second one** — every push arrives twice.
591
+
592
+ Both halves look correct in isolation, which is why the strategy is a `config.ts` flag branched on in `backgroundHandler.ts` rather than a comment someone deletes.
593
+
594
+ ---
595
+
596
+ ## Gotchas that will cost you an afternoon
597
+
598
+ Every one of these was hit during implementation. All of them fail **silently**.
599
+
600
+ ### 1. Anything reading notification context must be a CHILD of the provider
601
+
602
+ The component that renders `<NotificationProvider>` cannot also call a hook that consumes the context — a component never sees a context it provides. Put the consumer in a null-rendering child instead:
603
+
604
+ ```tsx
605
+ <NotificationProvider …>
606
+ <SomeContextConsumer /> {/* renders null */}
607
+ <Navigator />
608
+ </NotificationProvider>
609
+ ```
610
+
611
+ Symptom: `useNotificationContext must be used within <NotificationProvider>` from a component that visibly _is_ inside it.
612
+
613
+ ### 2. Never put an unstable function in a scheduling effect's deps
614
+
615
+ A translate helper that returns a **new closure every render** in an effect's dependency array re-runs that effect on every render — and since `scheduleLocalNotifications` opens by cancelling everything under its prefix, overlapping runs delete the triggers the previous run just created. **Nothing ever survives to fire.**
616
+
617
+ Depend on a stable value (`i18n.language`, a string) and call a module-level `translate()` instead. Any feature that wires its own scheduling effect must check this — it presents as "the notifications just don't work", with everything else looking correct.
618
+
619
+ ### 3. Exact alarms will be refused, and the throw disappears
620
+
621
+ Android 12+ gates exact alarms behind `SCHEDULE_EXACT_ALARM`. NotifyKit **throws** when it is missing, and if the caller used `void schedule(...)` the rejection vanishes into a floating promise.
622
+
623
+ The module uses `alarmManager: { type: AlarmType.SET_AND_ALLOW_WHILE_IDLE }` — inexact, no permission, still fires in Doze. Not the deprecated `allowWhileIdle: true`, which maps to an _exact_ alarm.
624
+
625
+ Check the grant state with `dump()` below: `android.alarm` is `0` when denied.
626
+
627
+ ### 4. The manifest meta-data collides with RNFirebase
628
+
629
+ `@react-native-firebase/messaging` ships its own `default_notification_channel_id` with an **empty** value. Two declarations of the same `meta-data` name is a hard merge failure at `processDebugMainManifest`. The config plugin adds `tools:replace="android:value"` for exactly this.
630
+
631
+ ### 5. Use the modular Firebase API
632
+
633
+ RNFirebase v22 deprecated namespaced `messaging()`; the next major removes it. This module uses `getMessaging(getApp())` throughout, resolved through a **lazy getter** — `getApp()` throws if Firebase has not initialised, and `service.ts` is imported during the first render pass.
634
+
635
+ ---
636
+
637
+ ## Testing & debugging
638
+
639
+ The pure modules, the service boundary and `NotificationProvider` are covered, with no device required. The provider tests mock `service.ts` whole and drive each listener directly: permission re-reads, the never-prompts rule, token registration (only signed in AND granted), cold-start and running taps, route gating and de-duplication, foreground display, and the badge.
640
+
641
+ ```bash
642
+ yarn test src/notifications
643
+ ```
644
+
645
+ NotifyKit ships ESM and a native module, so `jest.setup.ts` maps it to the package's own `jest-mock`, which re-exports every enum as a real value. Firebase is stubbed to only the **modular** surface `service.ts` calls — the namespaced form is deliberately absent, so a regression to it fails loudly in tests rather than shipping a deprecation warning.
646
+
647
+ ### Inspecting a running app
648
+
649
+ Almost every failure here is silent, and Metro's Hermes runtime has no `require`, so there is no way to interrogate the module from outside without an explicit handle. `service.ts` installs one under `__DEV__`:
650
+
651
+ ```js
652
+ await globalThis.__notifications.dump();
653
+ // {
654
+ // authorizationStatus: 1, // 1 = AUTHORIZED
655
+ // android: { alarm: 0 }, // 0 = exact-alarm DENIED
656
+ // scheduledTriggerIds: [], // locally scheduled triggers
657
+ // primaryChannel: { importance: 4 }, // PRIMARY_CHANNEL_ID, 4 = HIGH
658
+ // primaryChannelBlocked: false,
659
+ // }
660
+
661
+ await globalThis.__notifications.fireTestNotification(); // bypasses scheduling
662
+ await globalThis.__notifications.scheduleLocalNotifications(triggers, opts);
663
+ ```
664
+
665
+ Read it top-down: permission → channel → scheduled ids. The first row that looks wrong is the cause. Stripped from release builds.
666
+
667
+ ### What you can test where
668
+
669
+ | Target | Local scheduled | Remote push |
670
+ | ---------------- | --------------- | --------------------------------------- |
671
+ | iOS Simulator | ✅ | ❌ no APNs token, so no FCM token |
672
+ | iOS device | ✅ | ✅ **required for any end-to-end test** |
673
+ | Android emulator | ✅ | ✅ needs a Play Services image |
674
+
675
+ Plan for a physical iPhone in the QA loop from day one — the simulator gap is the usual reason iOS push bugs are found late.
676
+
677
+ ---
678
+
679
+ ## Known limits
680
+
681
+ | Limit | Effect | Handling |
682
+ | ----------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
683
+ | Inexact Android alarms | **Measured ~69s late** on a Samsung SM-E236B (Android 14): scheduled 17:10:00, fired 17:11:09 | Accepted. `SCHEDULE_EXACT_ALARM` is Play-policy sensitive and needs a Console declaration; don't promise to-the-minute accuracy in copy. `notifee.openAlarmPermissionSettings()` is the opt-in path if precision ever matters more than review risk. |
684
+ | Trigger caps (50 Android / ~64 iOS) | Caps the number of pending **local** triggers | Only reachable if a feature schedules many at once. Remote push is unaffected. |
685
+ | OEM battery managers | Xiaomi/Oppo/Huawei kill alarms aggressively | No clean fix for local triggers. Android reality — another reason to prefer remote push for anything recurring. |
686
+ | iOS simulator | No remote push at all | Use a device. |
687
+
688
+ ---
689
+
690
+ ## Switching to FCM Mode
691
+
692
+ `ANDROID_DISPLAY_STRATEGY = 'app-draws'` makes NotifyKit draw every notification in every state, identically, with rich styles (BigPicture, Inbox, progress) available on remote pushes.
693
+
694
+ It requires:
695
+
696
+ 1. Backend sends **data-only** payloads built with `buildNotifyKitPayload()` from `react-native-notify-kit/server`.
697
+ 2. An iOS Notification Service Extension — generated by the config plugin via `ios: { notificationServiceExtension: true }`.
698
+
699
+ The client code already branches for it; `backgroundHandler.ts` calls `handleFcmMessage()` under that flag. Worth revisiting only if rich remote notifications become a requirement.
700
+
701
+ ---
702
+
703
+ ## Replacing the stack
704
+
705
+ NotifyKit is a community fork of Notifee, archived by Invertase in April 2026. It is actively maintained, carries the full upstream history, has migrated to the New Architecture (which archived Notifee has not — that alone makes it the only workable option on RN 0.86), and is the successor Invertase name. But it is **one maintainer**.
706
+
707
+ The mitigation is structural, not hopeful: **every NotifyKit and Firebase call lives in `service.ts`.** If the fork stalls, migrating to `expo-notifications` means rewriting that one file and adding a direct APNs sender on the backend — the same work as doing it today, deferred at no extra cost. Nothing else in the module knows which library is underneath.
708
+
709
+ Keep it that way: **never import `react-native-notify-kit` or `@react-native-firebase/messaging` outside `service.ts`, `channels.ts` and `backgroundHandler.ts`.**
710
+
711
+ ---
712
+
713
+ ## Verification & troubleshooting
714
+
715
+ ### Checklist
716
+
717
+ Work down the list — each step only makes sense once the one above it passes.
718
+
719
+ ```bash
720
+ # 1. Native config actually landed
721
+ npx expo config --type prebuild --json | jq '.ios.entitlements, .ios.infoPlist.UIBackgroundModes'
722
+
723
+ # 2. It builds
724
+ npx expo prebuild --clean && yarn ios:development # and android:development
725
+
726
+ # 3. Types and tests
727
+ yarn type-check && yarn test src/notifications
728
+ ```
729
+
730
+ Then on a **physical iPhone** and an Android device or Play-Services emulator:
731
+
732
+ | # | Check | Pass looks like |
733
+ | --- | ----------------------------------------------------- | ------------------------------------------------------------- |
734
+ | 1 | Launch the app | Android: channels exist under Settings → Apps → Notifications |
735
+ | 2 | `await globalThis.__notifications.dump()` | `authorizationStatus`, channel present, no throw |
736
+ | 3 | Visit the permission screen, tap the CTA | OS prompt appears (not a silent no-op) |
737
+ | 4 | Grant, then `dump()` again | `authorizationStatus: 1` |
738
+ | 5 | Check your backend | A token arrived for this user |
739
+ | 6 | Send a test push, **app foregrounded** | Banner appears — proves `onMessage` → `displayNotification` |
740
+ | 7 | Send one, **app backgrounded** | Tray notification, heads-up |
741
+ | 8 | Tap it | Lands on the route from `ROUTE_BY_TYPE`, not the home screen |
742
+ | 9 | **Force-quit**, send one, tap it | App cold-starts and still lands on the right route |
743
+ | 10 | Android: mute the primary channel in Settings, reopen | Banner shows the `channel-blocked` copy |
744
+
745
+ Step 9 is the one people skip and the one that breaks — it exercises the cold-start route queue.
746
+
747
+ ### Symptoms
748
+
749
+ Everything here fails silently, so match on symptom:
750
+
751
+ | Symptom | Likely cause |
752
+ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
753
+ | `getToken()` returns `null` on iOS | `aps-environment` entitlement missing from `app.config.ts`, or no APNs key in the Firebase console |
754
+ | No token on iOS, simulator only | Expected — simulators have no APNs. Use a device. |
755
+ | Permission prompt never appears on Android 13+ | `configureNotifications()` ran after the request, or not at all — no channel means no prompt |
756
+ | Android build fails at `processDebugMainManifest` | The channel plugin is missing from `app.config.ts` |
757
+ | Every push arrives **twice** on Android | The background handler is drawing on top of FCM — see [the duplicate trap](#the-android-duplicate-notification-trap) |
758
+ | Push arrives in background but **nothing** in foreground | Normal OS behaviour — you removed or broke the `displayNotification` call |
759
+ | Nothing at all when the app is force-quit | Payload is data-only. Android drops those to a killed app; add a `notification` block |
760
+ | Tap opens the app but never navigates | `type` is missing from `data`, or absent from `TYPE_BY_PAYLOAD_VALUE` — it degraded to `general` |
761
+ | Tap navigates, except from a cold start | Something reads notification context above the provider, or the route is in `AUTHENTICATED_ROUTES` and auth had not resolved |
762
+ | No heads-up, notifications land silently | Channel importance below HIGH, **or** the backend omitted `priority: "high"` — both halves are required |
763
+ | Locally scheduled triggers vanish immediately | An unstable dependency in the scheduling effect — [Gotcha 2](#2-never-put-an-unstable-function-in-a-scheduling-effects-deps) |