Registry / communication / react-onesignal

react-onesignal

library3.5.1jsnpmunverified

react-onesignal is a JavaScript/TypeScript module designed to streamline the integration of OneSignal's push notification, web push, and in-app messaging services into web applications. Currently at version 3.5.1, the library receives frequent patch and minor updates, indicating active development. While its name suggests a React-specific use, the library's documentation explicitly states it can be used in virtually any JavaScript front-end codebase. It acts as a wrapper around the OneSignal Web SDK, abstracting the direct script loading and providing a convenient, promise-based `init` method to configure the SDK. Key differentiators include its React-friendly API, managed script loading (with an option to override the script source), and strong TypeScript support, simplifying the development experience for push notification capabilities.

communication

npm install react-onesignal

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-ONESIGNAL

react-onesignal

communicationjavascriptv3.5.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OneSignal

✓ import OneSignal from 'react-onesignal';

✗ const OneSignal = require('react-onesignal');

The library primarily uses ES Module syntax. While CommonJS is supported since v3.3.0, ESM is the recommended pattern for modern React applications. OneSignal is a default export.

IDisplayableOSNotification

✓ import type { IDisplayableOSNotification } from 'react-onesignal';

✗ import { IDisplayableOSNotification } from 'react-onesignal';

This is a TypeScript type interface, requiring a type-only import for correct static analysis and to avoid bundling issues.

Slidedown

✓ await OneSignal.init({ appId: 'YOUR_APP_ID' }); OneSignal.Slidedown.promptPush();

✗ import { Slidedown } from 'react-onesignal';

Slidedown is a property of the initialized OneSignal object, not a separate named export. Access it after OneSignal has been successfully initialized.

This example demonstrates how to initialize OneSignal using the `init` function within a React component's `useEffect` hook, ensuring it's called only once. It shows how to await the initialization promise and conditionally render content based on the SDK's readiness.

import React, { useState, useEffect } from 'react'; import OneSignal from 'react-onesignal'; function PushNotificationHandler() { const [initialized, setInitialized] = useState(false); useEffect(() => { const initializeOneSignal = async () => { try { await OneSignal.init({ appId: process.env.ONE_SIGNAL_APP_ID ?? 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', safari_web_id: process.env.ONE_SIGNAL_SAFARI_WEB_ID ?? '', notifyButton: { enable: true, }, allowLocalhostAsSecureOrigin: true, }); setInitialized(true); console.log('OneSignal initialized successfully'); // You can prompt for push notifications here after initialization // OneSignal.Slidedown.promptPush(); } catch (error) { console.error('Failed to initialize OneSignal:', error); } }; if (!initialized) { initializeOneSignal(); } }, [initialized]); if (!initialized) { return <div>Loading push notifications...</div>; } return ( <div> <h1>Push Notifications Ready</h1> <p>OneSignal SDK is initialized and ready to use.</p> <button onClick={() => OneSignal.Slidedown.promptPush()}>Show Push Prompt</button> </div> ); } export default PushNotificationHandler;

Debug

Known issues

breakingVersion 3.0 introduced significant breaking changes. Existing implementations using v2.x or older will require updates. Consult the official 'Migration Guide' for detailed instructions.

fix

Refer to the 'MigrationGuide.md' file in the package's GitHub repository or documentation to adapt your code to the v3 API changes.

affects: >=3.0.0

gotchaThe `OneSignal.init()` function returns a Promise. It is crucial to await this promise or use its `.then()` method before attempting to call any other OneSignal SDK methods, otherwise, they might not be available or fully configured.

fix

Always use `await OneSignal.init(...)` in an `async` context or `OneSignal.init(...).then(() => { ... })` to ensure the SDK is fully loaded and ready before subsequent calls.

affects: >=3.0.0

gotchaWhile the package is named `react-onesignal`, it's explicitly stated to be usable in 'practically any JS front-end codebase'. Developers should be aware it's a wrapper for the OneSignal Web SDK and not a React-specific UI component library.

fix

Understand that the package provides an API wrapper, not React components. Integrate it by calling its `init` method and then using the exposed OneSignal SDK methods.

affects: >=3.0.0

gotchaIncorrect configuration of `path`, `serviceWorkerPath`, or `serviceWorkerUpdaterPath` options during `init` can lead to service worker registration failures, preventing push notifications from working correctly.

fix

Ensure that the service worker paths specified in the `init` options correctly point to the OneSignal service worker files within your deployed application. Verify these paths against your OneSignal setup and deployment structure.

affects: >=3.0.0

gotchaThe `IDisplayableOSNotification` interface and its `display()` method (added in v3.5.1) are for advanced notification handling. Misusing `preventDefault()` without subsequently calling `display()` (if intended) can result in notifications not being shown to the user.

fix

When using notification event listeners and `event.preventDefault()`, ensure you understand the lifecycle. If the notification should eventually be shown, explicitly call `notification.display()` at the appropriate time.

affects: >=3.5.1

Errors

Common errors & fixes

ReferenceError: OneSignal is not defined

Attempting to use `OneSignal` without importing it, or in a CommonJS environment without correctly requiring it after v3.3.0.

fix

Ensure `import OneSignal from 'react-onesignal';` is at the top of your file, or use `const OneSignal = require('react-onesignal');` for CJS.

TypeError: Cannot read properties of undefined (reading 'promptPush')

Calling OneSignal methods (e.g., `Slidedown.promptPush()`) before the `OneSignal.init()` promise has resolved.

fix

Always `await OneSignal.init(...)` or chain `.then()` to the `init` call before attempting to interact with other OneSignal SDK functionalities.

OneSignal SDK is not initialized.

This error occurs internally within the OneSignal SDK if you try to use its methods (e.g., `setExternalUserId`, `sendTag`) when `OneSignal.init()` has not been successfully called or completed.

fix

Verify that `OneSignal.init()` is called exactly once and its promise resolves successfully before any other OneSignal API calls. Check for any errors during the `init` process.

Failed to register service worker

The OneSignal service worker file is not found at the specified `path`, `serviceWorkerPath`, or `serviceWorkerUpdaterPath` during initialization, or there are network/CORS issues preventing its loading.

fix

Double-check the paths provided in the `init` options match the location of your OneSignal service worker files. Ensure these files are correctly deployed and accessible from your domain. Use browser developer tools to inspect service worker registration errors.

Upgrade

Version history

3.5.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/OneSignal/react-onesignal ↗

packagehttps://www.npmjs.com/package/react-onesignal ↗

homepagehttps://onesignal.com ↗