Getting Started

Copy a setup prompt with the install steps and the full markdown guide for this plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-background-task`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/background-task/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

@capgo/capacitor-background-task lets a Capacitor app register named periodic jobs for sync, cache refreshes, analytics delivery, and other background fetch operations.

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>

Then run:

npx cap sync ios

Import

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

Define A Task

Define the callback at module scope so it is registered as soon as the app is started by the operating system.

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

const SYNC_TASK = 'sync-offline-data';

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

Register The Schedule

Call registerTaskAsync after your app has enough context to enable the background job.

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

minimumInterval is in minutes. Android enforces a minimum of 15 minutes. iOS treats the value as an earliest begin date and may run later.

Check Status

const status = await BackgroundTask.getStatusAsync();
const isRegistered = await BackgroundTask.isTaskRegisteredAsync(SYNC_TASK);
const registeredTasks = await BackgroundTask.getRegisteredTasksAsync();

console.log({ status, isRegistered, registeredTasks });

Trigger A Test Run

Use the test trigger in development or QA. It calls every registered task immediately.

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Unregister A Task

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

iOS Expiration

iOS can stop a background task before your JavaScript work finishes. Listen for expiration events when cleanup or checkpointing matters.

const expiration = await BackgroundTask.addExpirationListener((event) => {
  console.warn('Background task expired', event.taskName, event.taskId);
});

await expiration.remove();

React Native Background Task Compatibility

The plugin also exposes a small compatibility layer for apps migrating from react-native-background-task.

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

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

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

Production Notes

Background scheduling is opportunistic, not exact.
Keep work short and idempotent.
Persist any state you need before returning BackgroundTaskResult.Success.
Avoid relying on background tasks for user-visible deadlines or alarms.