RealtimeKeep your app up to date
AuthenticationOver 80+ OAuth integrations
Convex Components
ComponentsIndependent, modular, TypeScript building blocks for your backend.
Open sourceSelf host and develop locally
AI CodingGenerate high quality Convex code with AI
Compare
Convex vs. Firebase
Convex vs. Supabase
Convex vs. SQL
DocumentationGet started with your favorite frameworks
SearchSearch across Docs, Stack, and Discord
TemplatesUse a recipe to get started quickly
Convex for StartupsStart and scale your company with Convex
Convex ChampionsAmbassadors that support our thriving community
Convex CommunityShare ideas and ask for help in our community Discord
Stack
Stack

Stack is the Convex developer portal and blog, sharing bright ideas and techniques for building with Convex.

Explore Stack
BlogDocsPricing
GitHub
Log inStart building
Back to Components

Expo Push Notifications

get-convex's avatar
get-convex/expo-push-notifications
View repo
GitHub logoView package

Category

Integrations
Expo Push Notifications hero image
npm install @convex-dev/expo-push-notifications

This is a Convex component that integrates with Expo's push notification API to allow sending mobile push notifications to users of your app. It will batch calls to Expo's API and handle retrying delivery.

Demo GIF

Demo of sending push notifications

Example usage:
// App.tsx
<Button
  onPress={() => {
    void convex.mutation(api.example.sendPushNotification, {
      to: otherUser,
      title: `Hi from ${currentUser.name}`,
    });
  }}
>
  <Text>Say hi!</Text>
</Button>
// convex/example.ts
export const sendPushNotification = mutation({
  args: { title: v.string(), to: v.id("users") },
  handler: async (ctx, args) => {
    // Sending a notification
    return pushNotifications.sendPushNotification(ctx, {
      userId: args.to,
      notification: {
        title: args.title,
      },
    });
  },
});

Pre-requisite: Convex#

You'll need an existing Convex project to use the component. Convex is a hosted backend platform, including a database, serverless functions, and a ton more you can learn about here.

Run npm create convex or follow any of the quickstarts to set one up.

Installation#

Install the component package:

npm i @convex-dev/expo-push-notifications

Create a convex.config.ts file in your app's convex/ folder and install the component by calling use:

// convex/convex.config.ts
import { defineApp } from "convex/server";
import pushNotifications from "@convex-dev/expo-push-notifications/convex.config";

const app = defineApp();
app.use(pushNotifications);
// other components

export default app;

Instantiate the PushNotifications client in your Convex functions:

// convex/example.ts
import { PushNotifications } from "@convex-dev/expo-push-notifications";

const pushNotifications = new PushNotifications(components.pushNotifications);

It takes in an optional type parameter (defaulting to Id<"users">) for the type to use as a unique identifier for push notification recipients:

import { PushNotifications } from "@convex-dev/expo-push-notifications";

export type Email = string & { __isEmail: true };

const pushNotifications = new PushNotifications<Email>(
  components.pushNotifications
);

Registering a user for push notifications#

Get a user's push notification token following the Expo documentation here, and record it using a Convex mutation:

// convex/example.ts
export const recordPushNotificationToken = mutation({
  args: { token: v.string() },
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    await pushNotifications.recordToken(ctx, {
      userId,
      pushToken: args.token,
    });
  },
});

You can pause and resume push notification sending for a user using the pausePushNotifications and resumePushNotifications methods.

To determine if a user has a token and their pause status, you can use getStatusForUser.

Send notifications#

// convex/example.ts
export const sendPushNotification = mutation({
  args: { title: v.string(), to: v.string() },
  handler: async (ctx, args) => {
    const pushId = await pushNotifications.sendPushNotification(ctx, {
      userId: args.to,
      notification: {
        title: args.title,
      },
    });
  },
});

You can use the ID returned from sendPushNotifications to query the status of the notification using getNotification. Using this in a query allows you to subscribe to the status of a notification.

You can also view all notifications for a user with getNotificationsForUser.

Troubleshooting#

To add more logging, provide PushNotifications with a logLevel in the constructor:

const pushNotifications = new PushNotifications(components.pushNotifications, {
  logLevel: "DEBUG",
});

The push notification sender can be shutdown gracefully, and then restarted using the shutdown and restart methods.

Get your app up and running in minutes
Start building
Convex logo
ProductSyncRealtimeAuthOpen sourceAI codingChefFAQPricing
DevelopersDocsBlogComponentsTemplatesStartupsChampionsChangelogPodcastLLMs.txt
CompanyAbout usBrandInvestorsBecome a partnerJobsNewsEventsTerms of servicePrivacy policySecurity
SocialTwitterDiscordYouTubeLumaBlueskyGitHub
A Trusted Solution
  • SOC 2 Type II Compliant
  • HIPAA Compliant
  • GDPR Verified
©2025 Convex, Inc.