tauri-plugin-background-service

A Tauri v2 plugin that manages long-lived background service lifecycle across all platforms (Android, iOS, Windows, macOS, Linux).

You implement a single BackgroundService trait on your own struct. The plugin spawns it in a Tokio task, manages OS-specific keepalive mechanisms (Android foreground service, iOS BGTaskScheduler, desktop OS service), and provides helpers for notifications and event emission. No business logic lives in the plugin — only lifecycle management.

Use getPlatformCapabilities() at runtime to query what the current platform can guarantee for background execution survival.

Platform Guarantees

Background service survival varies significantly across platforms. The table below uses three guarantee levels:

Android: Foreground Service with persistent notification. START_STICKY enables OS restart under memory pressure (best-effort). Boot recovery via enableAutoRestart(). Android 15 dataSync type has a 6-hour cumulative timeout. OEM battery optimization may kill services.

iOS: BGTaskScheduler requests periodic execution windows (~30 seconds every 15+ minutes). Force-quitting the app kills all background tasks and prevents relaunch — this is an iOS design limitation.

Desktop: In-process mode runs as a standard Tokio task. OS-service mode (systemd/launchd, requires desktop-service feature) provides guaranteed background execution and survives app close/reboot when autostart is enabled.

Platform Support

Installation

Rust

Add the plugin to your app's Cargo.toml:

[dependencies]
tauri = { version = "2" }
tauri-plugin-notification = "2"
tauri-plugin-background-service = "0.7"

npm (TypeScript API)

npm install tauri-plugin-background-service

Rust Usage

1. Implement the BackgroundService trait

Create a struct and implement BackgroundService<R> with init() and run() methods:

use async_trait::async_trait;
use tauri::Runtime;
use tauri_plugin_background_service::{BackgroundService, ServiceContext, ServiceError};

pub struct MyService {
    tick_count: u64,
}

impl MyService {
    pub fn new() -> Self {
        Self { tick_count: 0 }
    }
}

#[async_trait]
impl<R: Runtime> BackgroundService<R> for MyService {
    async fn init(&mut self, _ctx: &ServiceContext<R>) -> Result<(), ServiceError> {
        // One-time setup: load config, open handles, seed state
        Ok(())
    }

    async fn run(&mut self, ctx: &ServiceContext<R>) -> Result<(), ServiceError> {
        let mut interval = tokio::time::interval(std::time::Duration::from_secs(10));

        loop {
            tokio::select! {
                _ = ctx.shutdown.cancelled() => break,
                _ = interval.tick() => {
                    self.tick_count += 1;
                    // Emit events to JS
                    let _ = ctx.app.emit("my-service://tick", self.tick_count);
                    // Show local notifications
                    ctx.notifier.show("Tick", "Service is alive");
                }
            }
        }

        Ok(())
    }
}

2. Register the plugin

In your main.rs, register tauri-plugin-notification before the background-service plugin:

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_notification::init())
        .plugin(tauri_plugin_background_service::init_with_service(
            || MyService::new(),
        ))
        .run(tauri::generate_context!())
        .expect("error while running application");
}

3. Add plugin configuration

In your tauri.conf.json, add the plugin configuration. It can be empty:

{
  "plugins": {
    "background-service": {}
  }
}

ServiceContext

The ServiceContext<R> passed to init() and run() provides:

• notifier — Fire local notifications via ctx.notifier.show("Title", "Body")
• app — Emit events to JS via ctx.app.emit("my-event", &payload)
• shutdown — A CancellationToken that resolves when stopService() is called. Always include it in tokio::select!
• service_label — Android notification text, always String (mobile only, behind #[cfg(mobile)])
• foreground_service_type — Android foreground service type string, always String (mobile only, behind #[cfg(mobile)])

TypeScript Usage

import {
  startService,
  stopService,
  isServiceRunning,
  getServiceState,
  onPluginEvent,
  getPlatformCapabilities,
  enableAutoRestart,
  disableAutoRestart,
  getDesiredServiceState,
  validateBackgroundServiceSetup,
  normalizeBackgroundServiceError,
} from 'tauri-plugin-background-service';

// Query platform capabilities (call early to set UI expectations)
const caps = await getPlatformCapabilities();
console.log(caps.backgroundExecution);  // 'guaranteed' | 'bestEffort' | 'unsupported'
console.log(caps.survivesReboot);       // 'guaranteed' | 'bestEffort' | 'unsupported'

// Start the service (optionally configure the Android notification label)
await startService({ serviceLabel: 'Syncing data' });

// Check if running (simple boolean)
const running = await isServiceRunning();

// Query detailed service state
const status = await getServiceState();
console.log(status.state); // 'idle' | 'initializing' | 'running' | 'stopped'
console.log(status.lastError); // null or error message
console.log(status.desiredRunning); // true | false | undefined
console.log(status.nativeState); // 'idle' | 'running' | 'timeout' | ... | undefined

// Enable auto-restart for recovery after process kill / reboot
await enableAutoRestart();

// Listen to lifecycle events
const unlisten = await onPluginEvent((event) => {
  switch (event.type) {
    case 'started':
      console.log('Service started');
      break;
    case 'stopped':
      console.log('Service stopped:', event.reason);
      break;
    case 'error':
      console.error('Service error:', event.message);
      break;
  }
});

// Validate your platform setup (checks permissions, manifest entries)
const report = await validateBackgroundServiceSetup();
if (!report.ok) {
  for (const err of report.errors) {
    console.error(`[${err.code}] ${err.message}`);
    if (err.fix) console.error(`  Fix: ${err.fix}`);
  }
}

// Typed error handling (opt-in helper)
try {
  await startService({ serviceLabel: 'Syncing' });
} catch (e) {
  const err = normalizeBackgroundServiceError(e);
  console.error(`[${err.code}] ${err.message}`);
}

// Stop the service and disable recovery
await stopService();
await disableAutoRestart();

// Clean up listener
unlisten();

Desktop Service API

When the desktop-service Cargo feature is enabled:

import {
  installService,
  uninstallService,
  startOsService,
  stopOsService,
  restartOsService,
  getOsServiceStatus,
} from 'tauri-plugin-background-service';

// Install as OS-level daemon (systemd / launchd)
await installService();

// Check OS service status
const status = await getOsServiceStatus();
console.log(status.installed);    // 'notInstalled' | 'installed' | 'running'
console.log(status.ipcConnected); // true | false

// Manage the OS service lifecycle
await startOsService();
await stopOsService();
await restartOsService();

// Uninstall the OS service
await uninstallService();

Permissions

Add these to your app's capability configuration:

{
  "permissions": [
    "background-service:allow-start",
    "background-service:allow-stop",
    "background-service:allow-is-running",
    "background-service:allow-get-service-state",
    "background-service:allow-get-platform-capabilities"
  ]
}

For auto-restart and desired-state:

"background-service:allow-enable-auto-restart",
"background-service:allow-disable-auto-restart",
"background-service:allow-get-desired-service-state"

For setup validation:

"background-service:allow-validate-setup"

For desktop service mode, also add:

"background-service:allow-install-service",
"background-service:allow-uninstall-service",
"background-service:allow-start-os-service",
"background-service:allow-stop-os-service",
"background-service:allow-restart-os-service",
"background-service:allow-get-os-service-status"

Platform Notes

Android

The plugin uses a Foreground Service with a persistent notification to reduce the likelihood of the OS killing the process while backgrounded. Required additions to your app's AndroidManifest.xml (the plugin's manifest already declares these):

• FOREGROUND_SERVICE and FOREGROUND_SERVICE_DATA_SYNC permissions
• POST_NOTIFICATIONS runtime permission (requested automatically on Android 13+)
• foregroundServiceType="dataSync" on the service declaration (see Android Guide for all 14 valid types)
• stopWithTask="false" ensures the service survives when the user swipes the app away
• START_STICKY causes the OS to restart the service if killed under memory pressure

When the service is restarted by the OS, the Rust process is new. Persist any state you need to restore in run() and reload it in init().

iOS

iOS background execution is best-effort scheduled execution. The plugin uses BGTaskScheduler to request periodic execution windows (~30 seconds every 15+ minutes). startService() returns a structured scheduling result indicating which task types were accepted. Force-quitting the app kills all background tasks and prevents relaunch. Required Info.plist additions:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER).bg-refresh</string>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER).bg-processing</string>
</array>
<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>processing</string>
</array>

While the app is foregrounded, your run() loop executes continuously. When backgrounded, Tokio freezes after ~30 seconds. Design your service to handle intermittent execution windows gracefully.

Desktop (Windows, macOS, Linux)

No special OS integration is needed. The service runs as a standard Tokio task and continues as long as the app process is alive.

For OS-level daemon mode (systemd / launchd), enable the desktop-service Cargo feature:

tauri-plugin-background-service = { version = "0.7", features = ["desktop-service"] }

Links

Documentation (relative paths — works on GitHub and crates.io):

• Getting Started
• API Reference
• Android Guide
• iOS Guide
• Desktop Guide
• Troubleshooting
• Migration Guide

Community (absolute URLs — required for crates.io compatibility):

• Contributing
• Changelog
• Security
• Architecture

License

SPDX-License-Identifier: MIT OR Apache-2.0