Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ivangonzalezg/react-native-background-guardian/llms.txt

Use this file to discover all available pages before exploring further.

Keep Your React Native Apps Alive in the Background

Prevent Android from killing background processes with Wake Locks, battery optimization exemptions, and OEM-specific protections. iOS-safe with no-op implementation.

Get StartedAPI Reference

Quick start

Get your app protected from background restrictions in minutes

1

Install the package

Add React Native Background Guardian to your project using your preferred package manager:
npm install react-native-background-guardian
For iOS, install pods:
cd ios && pod install
2

Import and use wake locks

Import the library and acquire a wake lock to keep the CPU running during background tasks:
import BackgroundGuardian from 'react-native-background-guardian';

// Acquire wake lock before starting background work
const acquired = await BackgroundGuardian.acquireWakeLock('MyBackgroundTask');

if (acquired) {
  // Perform your background work
  await doBackgroundWork();
  
  // Release when done
  await BackgroundGuardian.releaseWakeLock();
}
3

Request battery optimization exemption

Check if your app is exempt from battery optimizations and request exemption if needed:
// Check current status
const isIgnoring = await BackgroundGuardian.isIgnoringBatteryOptimizations();

if (!isIgnoring) {
  // Show the system dialog to request exemption
  await BackgroundGuardian.requestBatteryOptimizationExemption();
}
Google Play has restrictions on using REQUEST_IGNORE_BATTERY_OPTIMIZATIONS. Only use this if your app genuinely requires background execution (messaging, health tracking, device management, etc.).
4

Handle OEM-specific restrictions

Many manufacturers (Xiaomi, Huawei, Samsung) have additional battery optimization. Guide users to whitelist your app:
const manufacturer = await BackgroundGuardian.getDeviceManufacturer();

if (['xiaomi', 'huawei', 'oppo', 'vivo'].includes(manufacturer ?? '')) {
  // Open OEM-specific settings
  await BackgroundGuardian.openOEMSettings();
}

Explore by topic

Everything you need to keep your app running reliably in the background

Wake Lock Management

Keep the CPU running during background tasks with partial and screen wake locks.

Battery Optimization

Request exemption from Doze mode and App Standby restrictions.

OEM Restrictions

Navigate manufacturer-specific battery savers from Xiaomi, Samsung, Huawei, and more.

Doze & App Standby

Understand Android’s power-saving features and how to work with them.

Key features

Wake Lock Management

Keep CPU running during background tasks with partial and screen wake locks.

Battery Exemption

Request Doze mode whitelist to run background tasks more freely.

OEM-Specific Settings

Navigate to manufacturer battery settings for Xiaomi, Samsung, Huawei, and more.

Cross-Platform

iOS-safe implementation with no-op methods that return safe defaults.

TypeScript Support

Full type definitions included for excellent IDE autocomplete and type safety.

New Architecture Ready

Built as a Turbo Module for React Native’s new architecture.

Resources

Usage Examples

Real-world examples for audio players, location tracking, and kiosk mode.

Platform Differences

Understand how the library behaves on Android vs iOS.

Testing & Debugging

Test Doze mode with ADB and debug wake lock issues.

OEM Compatibility

Complete list of supported manufacturers and their settings.

Troubleshooting

Common issues and solutions for wake locks and battery optimization.

FAQ

Frequently asked questions about background execution.

Ready to get started?

Install React Native Background Guardian and start protecting your app from aggressive battery optimization today.

View QuickstartView on GitHub