---
name: bijection-expo-push-notifications
description: "Evaluate and integrate the Expo Push Notifications component with Bijection."
---

# Expo Push Notifications

Mobile push delivery

- Package: @bijectionhq/expo-push-notifications
- Category: Messaging
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/expo-push-notifications/tree/23226f12ed35cc97a46e748480462660432d4ce7
- Upstream: https://github.com/convex/expo-push-notifications/tree/d8a2a855d97031cd7646352d6087b9eb490a07f6
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/expo-push-notifications

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/expo-push-notifications.git
cd expo-push-notifications
git checkout 23226f12ed35cc97a46e748480462660432d4ce7
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @convex-dev/expo-push-notifications. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Expo Push Notifications. Follow the installation and configuration steps exactly.

# Expo Push Notifications

## Instructions

This component integrates Convex with Expo's push notification API to send mobile push notifications to app users. It handles batching multiple notifications into efficient API calls, implements exponential backoff retry logic for failed deliveries, and manages user token registration and pause states. The component uses Convex's workpool for parallel processing and provides real-time notification status tracking through queries.

### Installation

```bash
npm install @convex-dev/expo-push-notifications
```

Current npm version: `@convex-dev/expo-push-notifications@0.4.2`

## Use cases

- Building a chat or messaging app where you need to notify users of new messages when they're not actively using the app
- Creating a social platform that sends push notifications for likes, comments, follows, or other user interactions
- Implementing reminder or scheduling features that need to alert users at specific times or when conditions are met
- Adding notification capabilities to e-commerce apps for order updates, shipping notifications, or promotional messages
- Building team collaboration tools that notify members about project updates, mentions, or deadline reminders

## How it works

The component starts by registering user push tokens through the `recordToken` method, which stores Expo push notification tokens in Convex. When sending notifications via `sendPushNotification`, it looks up the user's token, validates their pause status, and inserts a notification record with "awaiting_delivery" state.

The batching system uses time-bucket markers to group notifications efficiently and schedules batch runs using Convex's scheduling system. A workpool processes multiple batches in parallel with configurable `maxParallelism`, marking notifications as "in_progress" to prevent duplicate processing.

The component handles partial failures by parsing Expo's batch responses and updating individual notification states accordingly. Temporary failures like `MessageRateExceeded` are moved to "needs_retry" status with exponential backoff, while successful deliveries are marked as "delivered". You can query notification status in real-time using `getNotification` and track delivery progress through Convex queries.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Expo Push Notifications is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Fexpo-push-notifications)
- [GitHub repository](https://github.com/get-convex/expo-push-notifications)
- [Convex Components Directory](https://www.convex.dev/components/push-notifications)
- [Convex documentation](https://docs.convex.dev)