@capgo/capacitor-background-task

Periodic background task scheduling for Capacitor apps. It follows the practical feature set of Expo BackgroundTask: named tasks, persistent registration, status checks, unregistering, a testing trigger, and iOS expiration events.

What It Does

• 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.

Limits

• 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.

Compatibility

Policy:

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

Install

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

iOS Setup

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>

Usage

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,
});

Testing

await BackgroundTask.triggerTaskWorkerForTestingAsync();

React Native Compatibility

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

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

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

Example App

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

API

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

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

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

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

getRegisteredTasksAsync() => Promise<string[]>

getPendingTaskRunsAsync() => Promise<BackgroundTaskEvent[]>

getStatusAsync() => Promise<BackgroundTaskStatus>

triggerTaskWorkerForTestingAsync() => Promise<boolean>

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

define(callback: BackgroundTaskCallback) => void

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

cancel() => Promise<void>

statusAsync() => Promise<ReactNativeBackgroundTaskStatus>

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