expo-background-fetch

55.0.15 verified Sat Apr 25 auth: no javascript

Provides a universal API for performing background fetch tasks in Expo and React Native apps, allowing periodic data fetching even when the app is in the background. Current stable version is 55.0.15, updated alongside the Expo SDK release cycle (roughly quarterly). Key differentiators: built on top of iOS BGTaskScheduler and Android WorkManager for reliable execution, integrated with Expo's manifest and permissions system. Unlike bare React Native plugins, handles Expo managed workflow and development builds seamlessly. Supports minimum interval configuration and status callbacks.

Common errors

error TypeError: Cannot read properties of undefined (reading 'BackgroundFetchResult') ↓

cause Using default import instead of namespace import.

fix

Replace 'import BackgroundFetch from ...' with 'import * as BackgroundFetch from ...'

error BackgroundFetchStatus not available on iOS simulator ↓

cause Background fetch is not supported on iOS simulator.

fix

Test on a real device or use Expo's development build with a physical device.

error Task 'background-fetch-task' is not defined. Use TaskManager.defineTask to define it. ↓

cause Trying to register a task without defining it first.

fix

Call TaskManager.defineTask(taskName, handler) before BackgroundFetch.registerTaskAsync().

error Background timer is not running because the app is in the background and the background task has been suspended. ↓

cause Background fetch task may be interrupted by iOS/Android.

fix

Ensure the task is registered with proper options and the device is not in low power mode.

Warnings

gotcha Background fetch on iOS requires the 'background fetch' capability and may be throttled by iOS. Minimum interval is not guaranteed. ↓

fix Set minimumInterval to at least 15 minutes (900 seconds); test on a real device.

breaking expo-background-fetch 11.0.0 removed the 'BackgroundFetch.eventName' export. Use task names directly. ↓

fix Replace BackgroundFetch.eventName with string literals for task names.

deprecated BackgroundFetch.configureAsync() is deprecated in favor of registerTaskAsync(). ↓

fix Use TaskManager.defineTask() and BackgroundFetch.registerTaskAsync() instead.

gotcha Android background fetch may not work if app is force-stopped; startOnBoot only re-registers after reboot. ↓

fix Inform users that background tasks may be killed by the OS; use WorkManager for more control.

breaking Expo SDK 44+ requires app.json with 'backgroundFetch' plugin for Android. ↓

fix Add 'plugins': ['expo-background-fetch'] to app.json.

Install

npm install expo-background-fetch

yarn add expo-background-fetch

pnpm add expo-background-fetch

Imports

BackgroundFetch

wrong

const BackgroundFetch = require('expo-background-fetch')

correct

import * as BackgroundFetch from 'expo-background-fetch'

ESM-only; CommonJS require will fail in Expo's module resolution.

BackgroundFetch.BackgroundFetchStatus

wrong

import { BackgroundFetch } from 'expo-background-fetch' // BackgroundFetch is namespace, not a named export

correct

import { BackgroundFetchStatus } from 'expo-background-fetch'

Import specific types/constants as named exports from the module.

registerTaskAsync

wrong

BackgroundFetch.registerTaskAsync('task', {...}) // valid but can be destructured

correct

import { registerTaskAsync } from 'expo-background-fetch'

Recommended to destructure for clarity.

BackgroundFetchResult
```
import { BackgroundFetchResult } from 'expo-background-fetch'
```
TypeScript type for task result (NoData, NewData, Failed).

Quickstart

Defines a background fetch task, registers it with a minimum interval, and handles fetch results (NewData/Failed).

import * as BackgroundFetch from 'expo-background-fetch';
import * as TaskManager from 'expo-task-manager';

const BACKGROUND_FETCH_TASK = 'background-fetch-task';

TaskManager.defineTask(BACKGROUND_FETCH_TASK, async () => {
  try {
    const response = await fetch('https://example.com/data');
    const data = await response.json();
    console.log('Background fetch data:', data);
    return BackgroundFetch.BackgroundFetchResult.NewData;
  } catch (error) {
    console.error('Background fetch failed:', error);
    return BackgroundFetch.BackgroundFetchResult.Failed;
  }
});

async function registerFetchTask() {
  const status = await BackgroundFetch.getStatusAsync();
  if (status === BackgroundFetch.BackgroundFetchStatus.Available) {
    await BackgroundFetch.registerTaskAsync(BACKGROUND_FETCH_TASK, {
      minimumInterval: 15 * 60, // 15 minutes in seconds
      stopOnTerminate: false,
      startOnBoot: true,
    });
  }
}

registerFetchTask();