Awesome Open Source
Awesome Open Source

Welcome to onesignal-expo-plugin

Version Documentation Maintenance Twitter: onesignal

The OneSignal Expo plugin allows you to use OneSignal without leaving the managed workflow. Developed in collaboration with SweetGreen.


This plugin is an Expo Config Plugin. It extends the Expo config to allow customizing the prebuild phase of managed workflow builds (no need to eject to a bare workflow). For the purposes of OneSignal integration, the plugin facilitates automatically generating/configuring the necessary native code files needed to get the OneSignal React-Native SDK to work. You can think of adding a plugin as adding custom native code.

Supported environments:


expo install onesignal-expo-plugin

# npm
npm install react-native-onesignal

# yarn
yarn add react-native-onesignal

Configuration in app.json / app.config.js


Add the plugin to the front of the plugin array. It should be added automatically if you ran expo install. Just make sure it is the first plugin in the array and to configure any desired plugin props:


  "plugins": [
        "mode": "development",



export default {
  plugins: [
        mode: "development",

Plugin Prop

You can pass props to the plugin config object to configure:

Plugin Prop
mode required Used to configure APNs environment entitlement. "development" or "production"
devTeam optional Used to configure Apple Team ID. You can find your Apple Team ID by running expo credentials:manager e.g: "91SW8A37CR"
iPhoneDeploymentTarget optional Target IPHONEOS_DEPLOYMENT_TARGET value to be used when adding the iOS NSE. A deployment target is nothing more than the minimum version of the operating system the application can run on. This value should match the value in your Podfile e.g: "12.0".

OneSignal App ID

Add your OneSignal App ID to your Expo constants via the extra param:


  "extra": {
    "oneSignalAppId": "<YOUR APP ID HERE>"

You can then access the value to pass to the setAppId function:

import OneSignal from 'react-native-onesignal';
import Constants from "expo-constants";

Alternatively, pass the app ID directly to the function:



In your configuration file, make sure you set:

Property Details
version Your app version. Corresponds to CFBundleShortVersionString on iOS. This value will be used in your NSE* target's plist file.
ios.buildNumber Build number for your iOS standalone app. Corresponds to CFBundleVersion and must match Apple's specified format. This value will be used in your NSE* target's plist file.

* NSE = Notification Service Extension. Learn more about the NSE here.

EAS (Expo Application Services)

See our EAS documentation for help with EAS.

iOS Credentials: OneSignal + EAS

To distribute your iOS application via EAS, you will need to ensure your credentials are set up correctly. See our credentials setup guide for instructions.

Prebuild (optional)

Prebuilding in Expo will result in the generation of the native runtime code for the project (and ios and android directories being built). By prebuilding, we automatically link and configure the native modules that have implemented CocoaPods, autolinking, and other config plugins. You can think of prebuild like a native code bundler.

When you run expo prebuild we enter into a custom managed workflow which provides most of the benefits of bare workflows and managed workflows at the same time.

Why should I prebuild?

It may make sense to prebuild locally to inspect config plugin changes and help in debugging issues.


expo prebuild
# nukes changes and rebuilds
expo prebuild --clean

EAS Note: if you choose to stay in a fully managed workflow by not prebuilding, EAS will still run expo prebuild at build time. You can also prebuild locally but remain in a fully managed workflow by adding the android and ios directories to your .gitignore.


The following commands will prebuild and run your application. Note that for iOS, push notifications will not work in the Simulator.

# Build and run your native iOS project
expo run:ios

# Build and run your native Android project
expo run:android


Contributions, issues and feature requests are welcome!
Feel free to check issues page.

Show your support

Give a if this project helped you!



Copyright 2022 OneSignal.
This project is MIT licensed.

Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Typescript (255,712
Push Notifications (1,806
Onesignal (277
Eas (25
Onesignal Notifications (25