Install the package
Install the library using your preferred package manager:
npm install react-native-background-guardian
iOS setup
For iOS projects, install the native dependencies using CocoaPods:
On iOS, all library methods are no-ops that return safe default values. iOS handles background execution differently through Background Modes, so no additional configuration is needed.
Android setup
No additional setup is required for Android. The necessary permissions are automatically merged into your app’s manifest:
<!-- Required for Wake Lock functionality -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
<!-- Required for requesting battery optimization exemption -->
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
The REQUEST_IGNORE_BATTERY_OPTIMIZATIONS permission is restricted by Google Play. Your app must fall into specific acceptable use cases (messaging, health tracking, task automation, etc.) to use this permission. See the Introduction page for the full list of acceptable use cases. Verify installation
After installation, verify that the library is working by importing it in your code:
import BackgroundGuardian from 'react-native-background-guardian';
// Check if the module is available
const manufacturer = await BackgroundGuardian.getDeviceManufacturer();
console.log('Device manufacturer:', manufacturer);
Rebuild your app
After installing the library, rebuild your app to ensure native modules are linked properly:
npx react-native run-android
If you encounter any issues during installation, try cleaning your build:Android: cd android && ./gradlew cleaniOS: cd ios && rm -rf build && pod install
TypeScript support
The library includes full TypeScript type definitions out of the box. No additional @types packages are needed.
New Architecture support
React Native Background Guardian is built as a Turbo Module and fully supports React Native’s New Architecture. No special configuration is required.
