expo-background-task

Expo Android and iOS module for Background Task APIs.

This is a non-fork fork of expo-background-task from the expo/expo repository, published as @zykeco/expo-background-task. It includes bug fixes and the iosTaskType option that are not yet available upstream.

API documentation

• Documentation for the latest stable release
• Documentation for the main branch

Installation in managed Expo projects

For managed Expo projects, please follow the installation instructions in the API documentation for the latest stable release.

Installation in bare React Native projects

For bare React Native projects, you must ensure that you have installed and configured the expo package before continuing.

Add the package to your npm dependencies

npx expo install expo-background-task

Configure for Android

No additional set up necessary.

Configure for iOS

Run npx pod-install after installing the npm package.

In order to use BackgroundTask API in standalone, detached and bare apps on iOS, your app has to include the background task identifier in the Info.plist file. You can do this by adding the following XML snippet to your Info.plist file:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>com.expo.modules.backgroundtask.processing</string>
</array>

iOS Task Types

On iOS, background tasks are powered by Apple's BGTaskScheduler framework, which offers two distinct task types. You can choose between them using the iosTaskType option.

'refresh' (default)

Uses BGAppRefreshTaskRequest. This is the recommended choice for most apps.

await BackgroundTask.registerTaskAsync('myTask', {
  minimumInterval: 15, // minutes
  // iosTaskType: 'refresh', — this is the default, no need to specify
});

When to use:

• Periodic content syncs (e.g. fetching new messages, updating a feed)
• Lightweight data updates that complete quickly
• Any task that should run frequently in the background

Characteristics:

• Aggressive scheduling — iOS typically runs these every ~15–30 minutes when conditions allow
• ~30 second execution limit
• Only supports earliestBeginDate (via minimumInterval) — no network/power constraints
• Requires fetch in UIBackgroundModes (added automatically by the config plugin)

'processing'

Uses BGProcessingTaskRequest. Use this for heavy, deferrable work.

await BackgroundTask.registerTaskAsync('heavyTask', {
  minimumInterval: 60,
  iosTaskType: 'processing',
  requiresNetworkConnectivity: true,
  requiresExternalPower: false,
});

When to use:

• Large database migrations or cleanup
• ML model training or inference
• Bulk data sync or media processing
• Any work that takes more than 30 seconds and can be deferred

Characteristics:

• iOS defers execution at its own discretion (hours to days)
• Several minutes of execution time allowed
• Supports requiresNetworkConnectivity and requiresExternalPower constraints
• Requires processing in UIBackgroundModes (added automatically by the config plugin)

Quick comparison

| | 'refresh' | 'processing' | |---|---|---| | Scheduling | Aggressive (~15–30 min) | Deferred (hours/days) | | Execution limit | ~30 seconds | Several minutes | | Best for | Periodic syncs, content updates | Heavy work, migrations, ML | | Network constraint | Not supported | Supported | | External power constraint | Not supported | Supported |

Additional options

| Option | Platforms | Default | Description | |---|---|---|---| | minimumInterval | iOS, Android | iOS: 720 (12h), Android: 1440 (24h) | Minimum interval in minutes between task executions | | iosTaskType | iOS only | 'refresh' | Which BGTask type to use | | requiresNetworkConnectivity | iOS, Android | true | Whether the task needs network access | | requiresExternalPower | iOS only | false | Whether the task needs external power (only for 'processing') |

Note: On Android, iosTaskType is ignored. Android uses WorkManager for all background work, which handles scheduling uniformly regardless of task complexity. The requiresNetworkConnectivity option does work on Android and controls the WorkManager network constraint.

Contributing

Contributions are very welcome! Please refer to guidelines described in the contributing guide.