@capgo/capacitor-background-task

Run periodic background tasks in your Capacitor app on iOS and Android, with named tasks that survive app restarts. Sync data or refresh content while the app is not open.

• Named tasks: registerTaskAsync() and unregisterTaskAsync() with options like minimumInterval and requiresNetwork.
• Status: isTaskRegisteredAsync(), getRegisteredTasksAsync() and getStatusAsync() report what is scheduled and available.
• Missed runs: getPendingTaskRunsAsync() returns runs recorded natively before JavaScript was ready.
• Testing: triggerTaskWorkerForTestingAsync() runs all registered tasks right away during development.
• Familiar API: an Expo BackgroundTask style API plus React Native background-task compatible schedule(), cancel() and finish().
• Platforms: iOS and Android. iOS uses BackgroundTasks, Android uses WorkManager. Web is a stub.

• Schedules periodic background work on Android with WorkManager.
• Schedules background processing on iOS with BGTaskScheduler.
• Supports multiple named tasks with minimumInterval in minutes.
• Emits retained task events so task runs recorded before JavaScript is ready can be drained.
• Provides a small react-native-background-task compatible API: define, schedule, cancel, statusAsync, and finish.

• Background tasks are not exact timers. Android and iOS decide when work actually runs.
• Android enforces a 15 minute minimum interval.
• iOS may delay runs substantially based on battery, network, and user behavior.
• iOS background tasks do not run in the simulator; use a physical device.
• This plugin cannot make an app run indefinitely in the background.

Policy:

• New plugins start at version 8.0.0 (Capacitor 8 baseline).
• Backward compatibility for older Capacitor majors is supported on demand.

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-background-task` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-background-task
npx cap sync

Add the background processing mode and permitted task identifier to ios/App/App/Info.plist:

<key>UIBackgroundModes</key>
<array>
  <string>processing</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>app.capgo.backgroundtask.processing</string>
</array>

Define tasks at module scope so they are available as soon as the app is started by the OS.

import { BackgroundTask, BackgroundTaskResult } from '@capgo/capacitor-background-task';

const SYNC_TASK = 'sync-offline-data';

BackgroundTask.defineTask(SYNC_TASK, async () => {
  try {
    await fetch('https://example.com/sync', { method: 'POST' });
    return BackgroundTaskResult.Success;
  } catch {
    return BackgroundTaskResult.Failed;
  }
});

await BackgroundTask.registerTaskAsync(SYNC_TASK, {
  minimumInterval: 30,
  requiresNetwork: true,
});

await BackgroundTask.triggerTaskWorkerForTestingAsync();

import { BackgroundTask } from '@capgo/capacitor-background-task';

BackgroundTask.define(async () => {
  await fetch('https://example.com/sync', { method: 'POST' });
});

await BackgroundTask.schedule({
  period: 1800,
});

The example-app/ folder is linked via file:.. and is intended for validating native wiring during development.

• defineTask(...)
• registerTaskAsync(...)
• unregisterTaskAsync(...)
• isTaskRegisteredAsync(...)
• getRegisteredTasksAsync()
• getPendingTaskRunsAsync()
• getStatusAsync()
• triggerTaskWorkerForTestingAsync()
• addExpirationListener(...)
• define(...)
• schedule(...)
• cancel()
• statusAsync()
• finish(...)
• Interfaces
• Type Aliases
• Enums

defineTask(taskName: string, callback: BackgroundTaskCallback) => void

Define the JavaScript callback for a task. Call this at module/global scope.

registerTaskAsync(taskName: string, options?: BackgroundTaskOptions | undefined) => Promise<void>

Register a named periodic background task.

unregisterTaskAsync(taskName: string) => Promise<void>

Unregister a named periodic background task.

isTaskRegisteredAsync(taskName: string) => Promise<boolean>

Check whether a named task is registered.

Returns: Promise<boolean>

getRegisteredTasksAsync() => Promise<string[]>

Return all registered task names.

Returns: Promise<string[]>

getPendingTaskRunsAsync() => Promise<BackgroundTaskEvent[]>

Return pending task runs that native recorded before JavaScript was ready.

Returns: Promise<BackgroundTaskEvent[]>

getStatusAsync() => Promise<BackgroundTaskStatus>

Return native background task availability.

Returns: Promise<BackgroundTaskStatus>

triggerTaskWorkerForTestingAsync() => Promise<boolean>

Trigger all registered tasks immediately for development/testing.

Returns: Promise<boolean>

addExpirationListener(listener: (event: BackgroundTaskEvent) => void) => Promise<PluginListenerHandle>

Listen for iOS expiration callbacks.

Returns: Promise<PluginListenerHandle>

define(callback: BackgroundTaskCallback) => void

React Native background-task compatible single-task define helper.

schedule(options?: ReactNativeBackgroundTaskOptions | undefined) => Promise<void>

React Native background-task compatible single-task scheduler.

cancel() => Promise<void>

React Native background-task compatible single-task cancel helper.

statusAsync() => Promise<ReactNativeBackgroundTaskStatus>

React Native background-task compatible status helper.

Returns: Promise<ReactNativeBackgroundTaskStatus>

finish(result?: BackgroundTaskResult | undefined) => Promise<void>

React Native background-task compatible finish helper. Normal Expo-style callbacks are finished automatically.

Payload emitted when native scheduling asks JavaScript to run a task.

Options for registering a periodic background task.

React Native background-task compatible schedule options.

React Native background-task compatible status payload.

Function executed for a background task.

(event: BackgroundTaskEvent): void | BackgroundTaskResult | Promise<void | BackgroundTaskResult>