@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

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | On demand |

Policy:

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

Install

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(...)
• registerTaskAsync(...)
• unregisterTaskAsync(...)
• isTaskRegisteredAsync(...)
• getRegisteredTasksAsync()
• getPendingTaskRunsAsync()
• getStatusAsync()
• triggerTaskWorkerForTestingAsync()
• addExpirationListener(...)
• define(...)
• schedule(...)
• cancel()
• statusAsync()
• finish(...)
• Interfaces
• Type Aliases
• Enums

defineTask(...)

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

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

| Param | Type | | -------------- | ------------------------------------------------------------------------- | | taskName | string | | callback | BackgroundTaskCallback |

registerTaskAsync(...)

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

Register a named periodic background task.

| Param | Type | | -------------- | ----------------------------------------------------------------------- | | taskName | string | | options | BackgroundTaskOptions |

unregisterTaskAsync(...)

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

Unregister a named periodic background task.

| Param | Type | | -------------- | ------------------- | | taskName | string |

isTaskRegisteredAsync(...)

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

Check whether a named task is registered.

| Param | Type | | -------------- | ------------------- | | taskName | string |

Returns: Promise<boolean>

getRegisteredTasksAsync()

getRegisteredTasksAsync() => Promise<string[]>

Return all registered task names.

Returns: Promise<string[]>

getPendingTaskRunsAsync()

getPendingTaskRunsAsync() => Promise<BackgroundTaskEvent[]>

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

Returns: Promise<BackgroundTaskEvent[]>

getStatusAsync()

getStatusAsync() => Promise<BackgroundTaskStatus>

Return native background task availability.

Returns: Promise<BackgroundTaskStatus>

triggerTaskWorkerForTestingAsync()

triggerTaskWorkerForTestingAsync() => Promise<boolean>

Trigger all registered tasks immediately for development/testing.

Returns: Promise<boolean>

addExpirationListener(...)

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

Listen for iOS expiration callbacks.

| Param | Type | | -------------- | --------------------------------------------------------------------------------------- | | listener | (event: BackgroundTaskEvent) => void |

Returns: Promise<PluginListenerHandle>

define(...)

define(callback: BackgroundTaskCallback) => void

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

| Param | Type | | -------------- | ------------------------------------------------------------------------- | | callback | BackgroundTaskCallback |

schedule(...)

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

React Native background-task compatible single-task scheduler.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------------- | | options | ReactNativeBackgroundTaskOptions |

cancel()

cancel() => Promise<void>

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

statusAsync()

statusAsync() => Promise<ReactNativeBackgroundTaskStatus>

React Native background-task compatible status helper.

Returns: Promise<ReactNativeBackgroundTaskStatus>

finish(...)

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

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

| Param | Type | | ------------ | --------------------------------------------------------------------- | | result | BackgroundTaskResult |

Interfaces

BackgroundTaskEvent

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

| Prop | Type | Description | | --------------- | -------------------- | ----------------------------------------------------------------------------------------------------------- | | taskName | string | Name passed to registerTaskAsync. | | taskId | string | Native run identifier. The JavaScript wrapper finishes it automatically when the defined callback resolves. | | timestamp | number | Native timestamp for the run. | | test | boolean | True when triggered through triggerTaskWorkerForTestingAsync. |

BackgroundTaskOptions

Options for registering a periodic background task.

| Prop | Type | Description | | --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | minimumInterval | number | Inexact interval in minutes between task runs. Defaults to 720 minutes. Android enforces a 15 minute minimum. iOS treats this as an earliest begin date and may run much later. | | requiresNetwork | boolean | Require an active network before running the native scheduler. Defaults to true. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

ReactNativeBackgroundTaskOptions

React Native background-task compatible schedule options.

| Prop | Type | Description | | ------------- | ------------------- | -------------------------------------------------------------------------- | | period | number | Desired seconds between each execution. Mapped to minimumInterval minutes. | | timeout | number | Android-only timeout hint kept for API compatibility. |

ReactNativeBackgroundTaskStatus

React Native background-task compatible status payload.

| Prop | Type | Description | | ----------------------- | -------------------- | -------------------------------------------------- | | available | boolean | Whether background tasks are available to the app. | | unavailableReason | string | Reason when unavailable. |

Type Aliases

BackgroundTaskCallback

Function executed for a background task.

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

Enums

BackgroundTaskResult

| Members | Value | Description | | ------------- | -------------- | ------------------------------- | | Success | 1 | The task finished successfully. | | Failed | 2 | The task failed. |

BackgroundTaskStatus

| Members | Value | Description | | ---------------- | -------------- | -------------------------------------------------------- | | Restricted | 1 | Background task scheduling is unavailable or restricted. | | Available | 2 | Background task scheduling is available. |