@sigx/lynx-background

Periodic background tasks for sigx-lynx — iOS BGTaskScheduler and Android WorkManager.

Run JS handlers while the app is backgrounded or closed: refresh content, sync queues, pull a feed, write to storage. Pairs with @sigx/lynx-network and @sigx/lynx-storage for the typical background-fetch story.

• iOS: BGAppRefreshTask (lightweight, ~30s budget) and BGProcessingTask (longer, charging-aware).
• Android: PeriodicWorkRequest (15-minute minimum interval) and OneTimeWorkRequest via androidx.work.

📚 Documentation

Full API, scheduling caveats, time budgets, permitted-identifier setup and live examples → sigx.dev/lynx/modules/background/overview

Install

pnpm add @sigx/lynx-background

sigx prebuild auto-discovers the package, links the native module, adds UIBackgroundModes to iOS, populates BGTaskSchedulerPermittedIdentifiers from the identifiers you declare in your app config, and adds the androidx.work dependency on Android. iOS task identifiers must be known at build time — declare them in signalx.config.ts.

A taste

import { Background } from '@sigx/lynx-background';
import { Storage } from '@sigx/lynx-storage';

// Register a handler at app startup, before the first foreground frame.
Background.setHandler('refresh-feed', async () => {
    const res = await globalThis.fetch('https://example.com/feed.json');
    await Storage.set('feed', JSON.stringify(await res.json()));
});

// Ask the OS to schedule it. Idempotent — call on every cold start.
await Background.register('refresh-feed', {
    minimumInterval: 15 * 60,   // 15 minutes (Android floor; iOS hint)
    requiresNetwork: true,
    type: 'fetch',              // iOS only; 'fetch' (default) or 'processing'
});

The full API, the platform frequency/time-budget caveats, the persistence model and platform gotchas are documented on the docs site.

License

MIT