Skip to content

Instantly share code, notes, and snippets.

@Xansiety

Xansiety/Push Notifications Setup for Expo App (SDK 54+).md

Last active November 15, 2025 22:54
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Xansiety/5e8d264c5391b7e287705efbca70b80f to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Xansiety/5e8d264c5391b7e287705efbca70b80f to your computer and use it in GitHub Desktop.
Download ZIP
Raw
Push Notifications Setup for Expo App (SDK 54+).md

Push Notifications Setup for Expo App (SDK 54+)

This guide explains how to configure push notifications in an Expo app using SDK 54 or later, based on the official Expo documentation:

It also includes additional system setup requirements such as installing and configuring a Java JDK, required for Android native builds.

1. Overview

Expo push notifications allow your app to receive messages even when it is not running. Beginning with Expo SDK 54, push notifications no longer work inside Expo Go. To test them, you must use a Development Build of your app.

A development build is a custom native binary that contains the native modules your app uses. Expo Go cannot include every module, so it removes push notification support.

2. Requirements

Before configuring push notifications, ensure the following dependencies are installed:

✔ Java JDK 17 (Required for Android builds)

Android Gradle tooling requires a full JDK installation.

Install Java 17 from Oracle or Temurin, then configure:

JAVA_HOME=C:\Program Files\Java\jdk-17
PATH=%JAVA_HOME%\bin

Verify installation:

java -version
javac -version

Both should report version 17.

✔ Node.js and Expo CLI

npm install -g expo-cli

✔ Android Studio (for emulators)

Expo uses the Android SDK and emulator tooling from Android Studio.

✔ EAS CLI (for dev builds)

npm install -g eas-cli

✔ ADB (Android Debug Bridge)

Required to install the APK on your device or emulator.

3. Configure Push Notifications

Why SDK 54 Requires a Development Build

Expo Go does not include the native module expo-notifications. When the app tries to use push notifications, Expo Go cannot load the native code.

To test push notifications, you must:

  1. Configure Firebase and push notifications
  2. Create a development build
  3. Install it on your device or emulator
  4. Run the app with full native permissions

Official reference: https://docs.expo.dev/develop/development-builds/expo-go-to-dev-build/

Step 1: Install the notifications package

npx expo install expo-notifications

Step 2: Configure Android permissions

IMPORTANT: On my case, this file doesnt exist on my project, and if its the same case for you, just ignore this step.

Expo automatically configures AndroidManifest.xml when using managed workflow.

For bare workflow, ensure you have:

android.permission.INTERNET
android.permission.VIBRATE
android.permission.POST_NOTIFICATIONS

Step 3: Firebase Configuration for Push Notifications (Expo SDK 54)

This section covers the setup required to support push notifications using Firebase Cloud Messaging (FCM) with Expo SDK 54. It integrates all steps from the official Expo guides:

Firebase Requirements Overview

To enable notifications on Android, two Firebase components are required:

  1. google-services.json — Configures Firebase inside the Android native build.
  2. Service Account Key JSON — Allows Expo/EAS to send push notifications using FCM v1.

Both must be configured correctly to avoid runtime errors such as:

default firebaseApp is not initialized
Make sure to call FirebaseApp.initialize(Context)

3.1 Configure google-services.json (Client-side Firebase Setup)

Firebase requires this file inside the Android native project to initialize FCM.

Step A — Download the correct file

In Firebase Console:

  1. Go to Project settings.
  2. Under Your apps, select the Android app with the correct package name.
  3. Click Download google-services.json.

Note: This is not the Admin SDK key. The correct file is always named exactly: google-services.json

Step B — Place it inside your Expo project

Place the file at the root of your Expo project:

project-root/
  google-services.json
  app.json
  package.json
Step C — Reference it in app.json
"android": {
  "package": "com.example.pushapp",
  "googleServicesFile": "./google-services.json",
  "useNextNotificationsApi": true
}

Expo will automatically copy this file into the correct native location during EAS builds.

Step D — Confirm the file exists
Test-Path ./google-services.json

Should return True.

Step E — Commit the file

It is safe to commit google-services.json to version control since it contains no secrets.

3.2 Configure FCM Service Account Key (Server-side Firebase Setup)

This key enables push delivery through Expo's servers using FCM v1.

Step A — Generate the Service Account Key

In Firebase Console:

  1. Go to Project settings → Service accounts.
  2. Click Generate new private key.
  3. Download the JSON (filename contains a random suffix).

This is the sensitive key used by Expo/EAS.

Step B — Upload the key to Expo

At Expo Dashboard:

https://expo.dev/accounts/<account>/projects/<project>/credentials

Upload the Service Account Key JSON under Android → Push Notifications (FCM).

Expo will now be able to deliver notifications via FCM v1.

Step 4: Request Permissions and Implement Notification Logic

Request permissions and obtain an Expo Push Token

import * as Notifications from 'expo-notifications';
import { Platform } from 'react-native';

export async function registerForPushNotificationsAsync() {
  const { status: existingStatus } = await Notifications.getPermissionsAsync();
  let finalStatus = existingStatus;

  if (existingStatus !== 'granted') {
    const { status } = await Notifications.requestPermissionsAsync();
    finalStatus = status;
  }

  if (finalStatus !== 'granted') {
    alert('Permission is required to receive notifications');
    return null;
  }

  const token = await Notifications.getExpoPushTokenAsync();
  console.log('Expo Push Token:', token.data);
  return token.data;
}

Add a notification handler

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: false,
  }),
});

Call the registration function in your root component:

useEffect(() => {
  registerForPushNotificationsAsync();
}, []);

4. Create and Deploy the Development Build

Step 1: Generate the Development Build with EAS

Run the following command to create a development build:

eas build --profile development --platform android

When Expo asks:

? Generate a new Android Keystore? » (Y/n)

Select: Y (recommended for development builds).

EAS will automatically:

  • Generate a new Android keystore
  • Store it securely on Expo servers
  • Use it to sign your development build

Note: This keystore does not affect production signing. It's safe, automatic, and ideal for testing features such as push notifications.

Step 2: Monitor Build Progress in Expo Dashboard

After running the build command, your build will be processed on Expo's servers.

Track your build progress:

  1. Go to your Expo Dashboard: https://expo.dev/
  2. Navigate to your project
  3. Go to Builds section
  4. You will see your build status in real-time (Queued → Building → Finished)

The dashboard shows:

  • Build status and progress percentage
  • Build logs for debugging
  • Estimated time remaining

Step 3: Download and Install the APK

Once the build finishes successfully:

  1. Download the APK from the Expo Dashboard

    • Click on the completed build
    • Download the APK file to your computer

  2. Install on your device or emulator:

    adb install path\to\app-development.apk

    Or simply drag and drop the APK file onto your emulator.

Step 4: Run the Development Build with Dev Client

Start the dev client to connect your app to your development server:

npx expo start --dev-client

The app will start on your device or emulator with full native support and hot reload enabled.

5. Testing Push Notifications

With your dev build running on a physical device or emulator:

  1. Copy the Expo Push Token

    • The token will be printed in the console when the app starts
    • It looks like: ExponentPushToken[...]

  2. Send a test notification

    Option A: Using the Expo Web Tool

    Option B: Using the Expo CLI

    expo push:send --to <your-token> --title "Hello!" --body "This is a test notification."

  3. Verify the notification arrives

    • If configured correctly, the notification should appear on your device
    • The app will trigger the notification handler you set up

  4. Test Hot Reload

    • While the dev client is running, make changes to your code
    • Press r in the terminal to reload the app
    • Your changes appear instantly without reinstalling the APK

6. Handling Android Keystore During Dev Builds

For development builds, the recommended choice is Y when generating a new keystore.

Only choose n if you already have your own .jks file and want to upload it manually — typically for production builds.

7. Notes for Production

When releasing your app:

  • Android uses Firebase Cloud Messaging (FCM)
  • iOS requires an Apple Developer key
  • EAS will guide you through this setup

Production builds must be generated with:

eas build --platform android

8. Summary

  • SDK 54 requires development builds to use push notifications
  • Install and configure Java JDK 17 for Android build tools
  • Use expo-notifications and request permissions from the user
  • Configure Firebase and google-services.json before building
  • Use the Expo Dashboard to monitor build progress and download APK
  • Install the APK and run with npx expo start --dev-client for hot reload support
  • Test notifications with a dev build, not Expo Go

Your app is now ready to receive push notifications!

Useful Links

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment