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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BackgroundFetch
✓ import * as BackgroundFetch from 'expo-background-fetch'
✗ const BackgroundFetch = require('expo-background-fetch')
ESM-only; CommonJS require will fail in Expo's module resolution.
BackgroundFetch.BackgroundFetchStatus
✓ import { BackgroundFetchStatus } from 'expo-background-fetch'
✗ import { BackgroundFetch } from 'expo-background-fetch' // BackgroundFetch is namespace, not a named export
Import specific types/constants as named exports from the module.
registerTaskAsync
✓ import { registerTaskAsync } from 'expo-background-fetch'
✗ BackgroundFetch.registerTaskAsync('task', {...}) // valid but can be destructured
Recommended to destructure for clarity.
BackgroundFetchResult
✓ import { BackgroundFetchResult } from 'expo-background-fetch'
TypeScript type for task result (NoData, NewData, Failed).
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();
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'BackgroundFetchResult')
Using default import instead of namespace import.
fixReplace 'import BackgroundFetch from ...' with 'import * as BackgroundFetch from ...'
BackgroundFetchStatus not available on iOS simulator
Background fetch is not supported on iOS simulator.
fixTest on a real device or use Expo's development build with a physical device.
Task 'background-fetch-task' is not defined. Use TaskManager.defineTask to define it.
Trying to register a task without defining it first.
fixCall TaskManager.defineTask(taskName, handler) before BackgroundFetch.registerTaskAsync().
Background timer is not running because the app is in the background and the background task has been suspended.
Background fetch task may be interrupted by iOS/Android.
fixEnsure the task is registered with proper options and the device is not in low power mode.
Audit
Dependencies
exporequiredPeer dependency required for Expo module system integration.