native_workmanager

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #claude-code #cli #windows #codex #developer-tools #dsh

native_workmanager

★ 13 Open GitHub ↗

Native WorkManager: High-performance Flutter background Task Chains with zero-overhead. Harness the full power of Android WorkManager & iOS BGTaskScheduler using pure Kotlin/Swift Workers.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">native_workmanager</h1>

Background tasks for Flutter — 25+ built-in workers, zero Flutter Engine overhead. 
 HTTP, file ops, image processing, encryption — all in pure Kotlin & Swift.

---

## The 30-second pitch

```dart
// Download → resize → upload — survives app kill, device reboot, low memory
await NativeWorkManager
  .beginWith(TaskRequest(id: 'dl',
    worker: NativeWorker.httpDownload(url: photoUrl, savePath: '/tmp/raw.jpg')))
  .then(TaskRequest(id: 'resize',
    worker: NativeWorker.imageProcess(inputPath: '/tmp/raw.jpg',
      outputPath: '/tmp/thumb.jpg', maxWidth: 512)))
  .then(TaskRequest(id: 'upload',
    worker: NativeWorker.httpUpload(url: uploadUrl, filePath: '/tmp/thumb.jpg')))
  .named('photo-pipeline')
  .enqueue();
```

No boilerplate. No native code to write. No `AndroidManifest.xml` changes. Each step retries independently — if the upload fails, only the upload retries.

---

## Quick Start

**1. Add the dependency:**

```yaml
dependencies:
  native_workmanager: ^1.4.3
```

**2. Initialize once in `main()`:**

```dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await NativeWorkManager.initialize();
  runApp(MyApp());
}
```

**3. Schedule a background task:**

```dart
await NativeWorkManager.enqueue(
  taskId: 'daily-sync',
  worker: NativeWorker.httpSync(url: 'https://api.example.com/sync'),
  constraints: const Constraints(requiresNetwork: true),
);
```

**iOS only** — run once to configure `BGTaskScheduler` automatically:

```bash
dart run native_workmanager:setup_ios
```

> **Flutter 3.38+ / UIScene apps:** fully supported since v1.3.2 — the plugin
> registers its BGTask launch handlers in an ObjC `+load` hook, before the app
> finishes launching, so the new UIScene plugin-registration timing cannot crash
> it (see [iOS Setup Guide §4b](doc/IOS_SETUP_GUIDE.md) and Issue #36). No extra
> AppDelegate code is required on either the old or the new template.

---

## Why developers switch from `workmanager`

The dominant `workmanager` plugin spins up a **full Flutter Engine per background task**: ~50–100 MB RAM, up to 3 seconds cold start, a Dart isolate the OS kills the moment memory gets tight. On Xiaomi/Samsung/Huawei devices with aggressive battery optimization, the engine never even starts.

`native_workmanager` runs tasks as pure Kotlin coroutines and Swift async functions — **no engine, no isolate, no cold-start penalty**.

| | `workmanager` | `native_workmanager` |
|---|:---:|:---:|
| Memory per task | ~50–100 MB | **~2–5 MB** |
| Task startup | 1,500–3,000 ms | **< 50 ms** |
| OOM Resilience | ❌ (Killed by OS) | ✅ (Survives system purge) |
| Built-in HTTP workers | ❌ | ✅ (resumable download, chunked upload, parallel) |
| Built-in image workers | ❌ | ✅ (resize, crop, convert, thumbnail — EXIF-aware) |
| Built-in crypto workers | ❌ | ✅ (AES-256-GCM, SHA-256/512, HMAC) |
| Task chains (A→B→C) | ❌ | ✅ (persist across reboots) |
| FGS Bypass (Android) | ❌ | ✅ (Bypass Doze/Standby with custom notifications) |
| Per-task progress stream | ❌ | ✅ |
| Retry ceiling (`maxRetries`) | ❌ (unbounded `Result.retry()`) | ✅ (capped on both platforms) |
| Survives device reboot | ✅ | ✅ |
| Remote Trigger (Push) | ❌ | ✅ (FCM/APNs + HMAC Security) |
| Custom Dart workers | ✅ | ✅ (opt-in via `DartWorker`) |

> **If you only do HTTP syncs and file ops, you probably don't need Dart workers at all.** Use the native workers directly — they're production-hardened and need zero engine overhead.

---

## Industrial-Grade OOM Resilience

Most Flutter background libraries fail because they boot a full Flutter Engine (50MB+ RAM) for every task. Under memory pressure, Android/iOS will kill these heavy processes first.

`native_workmanager` uses a **Zero-Engine Architecture**. Our Native Workers run in pure Kotlin/Swift, consuming only **~2MB of RAM**. This makes them "invisible" to the OS's memory killer.

### The OOM Survival Test
Even if the system is under extreme pressure and kills your app while a task is running, **your work is not lost**.
- **Android:** Managed by `WorkManager` with system-level persistence. Tasks are automatically rescheduled with exponential backoff.
- **iOS:** Recovers state from a native SQLite store the moment a new background window is granted.

> **See for yourself:** Run the "Simulate OOM Kill" demo in the example app. It crashes the app with a memory bomb, and you'll see the background task trigger successfully seconds later.

---

## 25+ Built-in Workers

All workers run natively. No Flutter Engine. No setup beyond `initialize()`.

| Category | Workers |
|----------|---------|
| **HTTP** | `httpDownload` (resumable), `httpUpload` (multipart), `multiUpload`, `parallelHttpDownload` (chunked), `httpSync`, `httpRequest` |
| **Image** | `imageProcess` — resize, crop, convert format, thumbnail (all via one EXIF-aware worker) |
| **PDF** | `pdfMerge`, `pdfCompress`, `pdfFromImages` |
| **Crypto** | `cryptoEncrypt` (AES-256-GCM), `cryptoDecrypt`, `hashFile` / `hashString` (SHA-256/512) |
| **File** | `fileCopy`, `fileMove`, `fileDelete`, `fileList`, `fileMkdir`, `fileCompress`, `fileDecompress` |
| **Storage** | `moveToSharedStorage` (Android MediaStore / iOS Files app) |
| **Real-time** | `webSocket` — Android |
| **Custom** | `custom` (bring your own native worker class), `DartWorker` (opt-in Dart callback) |

---

## Track progress in real time

`enqueue()` returns a `TaskHandler` that streams progress and completion events for that specific task — no manual filtering required.

```dart
final handler = await NativeWorkManager.enqueue(
  taskId: 'big-download',
  worker: NativeWorker.httpDownload(
    url: 'https://cdn.example.com/video.mp4',
    savePath: '/tmp/video.mp4',
  ),
);

// Stream progress for this task only
handler.progress.listen((p) {
  print('${p.progress}% — ${p.networkSpeedHuman} — ETA ${p.timeRemainingHuman}');
});

// Await completion
final result = await handler.result;
print(result.success ? 'Done!' : 'Failed: ${result.message}');
```

Or drop in the built-in widget:

```dart
TaskProgressCard(handler: handler, title: 'Downloading video')
```

---

## Task Chains

Chain workers into persistent pipelines. Each step only runs when the previous one succeeds, and the entire chain survives app kills and device reboots (SQLite-backed state).

```dart
await NativeWorkManager
  .beginWith(TaskRequest(
    id: 'download',
    worker: NativeWorker.httpDownload(
      url: 'https://cdn.example.com/report.pdf',
      savePath: '/tmp/report.pdf',
    ),
  ))
  .then(TaskRequest(
    id: 'encrypt',
    worker: NativeWorker.cryptoEncrypt(
      inputPath: '/tmp/report.pdf',
      outputPath: '/tmp/report.enc',
      password: vaultKey,
    ),
  ))
  .then(TaskRequest(
    id: 'upload',
    worker: NativeWorker.httpUpload(
      url: 'https://vault.example.com/store',
      filePath: '/tmp/report.enc',
    ),
  ))
  .named('secure-report-pipeline')
  .enqueue();
```

Use `.thenAll([...])` to run tasks in parallel, then continue the chain when all finish.

---

## Custom Dart Workers

For app-specific logic that must run in Dart, register a top-level function as a background worker:

```dart
@pragma('vm:entry-point')
Future<bool> syncHealthData(Map<String, dynamic>? input) async {
 final userId = input?['userId'] as String?;
 await uploadHealthMetrics(userId);
 return true;
}

// Register once at startup
NativeWorkManager.registerDartWorker('health-sync', syncHealthData);

// Schedule it
await NativeWorkManager.enqueue(
  taskId: 'sync-user-42',
  worker: DartWorker(callbackId: 'health-sync', input: {'userId': '42'}),
);
```

Dart workers boot a headless Flutter isolate (~50 MB, 1–2 s cold start). The isolate is cached for 5 minutes so back-to-back tasks pay the boot cost only once. For HTTP and file tasks, use native workers instead.

**Retry on failure** — return `false` (or throw) and the task retries under
`Constraints.maxRetries` and `backoffPolicy`/`backoffDelayMs`, then fails
permanently once the ceiling is hit (`maxRetries: 3` by default → up to 4 total
runs, enforced on both platforms since v1.4.0). Use `Constraints(maxRetries: 0)`
for fail-fast tasks that must never re-run:

```dart
await NativeWorkManager.enqueue(
  taskId: 'sync-user-42',
  worker: DartWorker(callbackId: 'health-sync', input: {'userId': '42'}),
  constraints: const Constraints(
    maxRetries: 2,                        // 1 initial run + 2 retries max
    backoffPolicy: BackoffPolicy.linear,
    backoffDelayMs: 30000,
  ),
);
```

Report progress from inside a `DartWorker` and it streams to `NativeWorkManager.progress` / `handler.progress` just like a native worker (Android and iOS):

```dart
@pragma('vm:entry-point')
Future<bool> syncHealthData(Map<String, dynamic>? input) async {
 final taskId = input?['__taskId'] as String?;
 await NativeWorkManager.reportDartWorkerProgress(taskId: taskId, progress: 50);
 // ... do work ...
 await NativeWorkManager.reportDartWorkerProgress(taskId: taskId, progress: 100);
 return true;
}
```

> **Android killed-app support** — When Android kills your app and WorkManager later fires a `DartWorker`, the process restarts without Flutter. Since **v1.3.0 this is zero-config**: the plugin's `androidx.startup` initializer restores the `callbackHandle` and installs its `WorkerFactory` automatically before any task fires — no custom `Application` class required. Apps that ship their own `Configuration.Provider` can opt out — see **[Android Setup Guide](doc/ANDROID_SETUP.md)**.

### Code generation for DartWorker

The companion [`native_workmanager_gen`](https://pub.dev/packages/native_workmanager_gen) package generates type-safe callback IDs and a worker registry from `@WorkerCallback` annotations, eliminating string-based registration and magic IDs:

```dart
@WorkerCallback('health-sync')
Future<bool> syncHealthData(Map<String, dynamic>? input) async { ... }

// Generated: WorkerCallbacks.healthSync, auto-registered in WorkerRegistry
```

---

## 🔌 Selective Plugin Registration (Recommended)

By default, `native_workmanager` runs with `registerPlugins: false`. This follows our **Zero-Engine I/O** principle to save RAM (~50MB+) and prevent hardware side-effects (like Bluetooth or Audio disconnects when a background task finishes).

If your `DartWorker` needs to use other plugins (e.g., `flutter_local_notifications`, `shared_preferences`), you should register them **selectively** on the native side. This is more efficient and stable than registering all plugins.

#### **1. Android (Kotlin)**
In your `MainActivity.kt` or `MainApplication.kt`:

```kotlin
import dev.brewkits.native_workmanager.NativeWorkmanagerPlugin
import io.flutter.embedding.engine.FlutterEngine
import com.dexterous.flutterlocalnotifications.FlutterLocalNotificationsPlugin

class MainActivity: FlutterActivity() {
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)
        
        NativeWorkmanagerPlugin.setPluginRegistrantCallback(object : NativeWorkmanagerPlugin.Companion.PluginRegistrantCallback {
            override fun registerWith(engine: FlutterEngine) {
                // Register ONLY the plugins you need in background
                engine.plugins.add(FlutterLocalNotificationsPlugin())
            }
        })
    }
}
```

#### **2. iOS (Swift)**
In your `AppDelegate.swift`:

```swift
import native_workmanager
import flutter_local_notifications

@main
@objc class AppDelegate: FlutterAppDelegate {
    override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        GeneratedPluginRegistrant.register(with: self)
        
        NativeWorkmanagerPlugin.setPluginRegistrantCallback { registry in
            // Manual registration for background engine
            FlutterLocalNotificationsPlugin.register(with: registry.registrar(forPlugin: "FlutterLocalNotificationsPlugin")!)
        }
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}
```

#### **3. Flutter (Dart)**
Keep `registerPlugins: false` to maintain peak performance:

```dart
await NativeWorkManager.initialize(
  registerPlugins: false, // Lean background engine
);
```

---

## Platform Support

| Feature | Android | iOS |
|---------|:-------:|:---:|
| One-time tasks | ✅ | ✅ |
| Periodic tasks | ✅ | ✅ (BGAppRefresh) |
| Exact-time triggers | ✅ | ✅ |
| Task chains (persistent) | ✅ | ✅ |
| Network / charging constraints | ✅ | ✅ |
| Per-task progress stream | ✅ | ✅ |
| Foreground service (long tasks) | ✅ | — |
| Custom Dart workers | ✅ | ✅ |
| Min OS version | Android 8.0 (API 26) | iOS 14.0 |

---

## Migrating from `workmanager`

Most migrations take under 10 minutes. The conceptual model is the same; the API is a strict superset.

| `workmanager` | `native_workmanager` |
|---|---|
| `Workmanager().initialize(...)` | `NativeWorkManager.initialize()` |
| `Workmanager().registerOneOffTask(...)` | `NativeWorkManager.enqueue(worker: NativeWorker.httpSync(...))` |
| `Workmanager().registerPeriodicTask(...)` | `NativeWorkManager.enqueue(trigger: TaskTrigger.periodic(...))` |
| Custom Dart callback | `DartWorker(callbackId: ...)` |

See [Migration Guide](doc/MIGRATION_GUIDE.md) for a step-by-step walkthrough.

---

## Common Use Cases

<details>
<summary>📥 Resumable large file download</summary>

```dart
await NativeWorkManager.enqueue(
 taskId: 'download-dataset',
 worker: NativeWorker.httpDownload(
 url: 'https://data.example.com/dataset.zip',
 savePath: '/tmp/dataset.zip',
 headers: {'Authorization': 'Bearer $token'},
 allowResume: true,
 ),
 constraints: const Constraints(requiresUnmeteredNetwork: true),
);
```
</details>

<details>
<summary>🔐 Encrypt &amp; upload sensitive file</summary>

```dart
await NativeWorkManager
 .beginWith(TaskRequest(
 id: 'encrypt',
 worker: NativeWorker.cryptoEncrypt(
 inputPath: '/documents/report.pdf',
 outputPath: '/tmp/report.enc',
 password: securePassword,
 ),
 ))
 .then(TaskRequest(
 id: 'upload',
 worker: NativeWorker.httpUpload(
 url: 'https://vault.example.com/store',
 filePath: '/tmp/report.enc',
 ),
 ))
 .named('secure-backup')
 .enqueue();
```
</details>

<details>
<summary>⏱ Periodic background sync</summary>

```dart
await NativeWorkManager.enqueue(
  taskId: 'hourly-sync',
  worker: NativeWorker.httpSync(url: 'https://api.example.com/sync'),
  trigger: TaskTrigger.periodic(
    const Duration(hours: 1),
    initialDelay: const Duration(minutes: 30), // Delay first run by 30m
  ),
  constraints: const Constraints(requiresNetwork: true),
  existingPolicy: ExistingTaskPolicy.keep,
);
```

> `initialDelay` on periodic tasks defers the first run instead of firing immediately on registration, saving resources when the app is first launched.
</details>

<details>
<summary>📸 Photo backup pipeline</summary>

```dart
await NativeWorkManager
 .beginWith(TaskRequest(
 id: 'compress',
 worker: NativeWorker.imageProcess(
 inputPath: photoPath,
 outputPath: '/tmp/photo_compressed.jpg',
 maxWidth: 1920,
 quality: 85,
 ),
 ))
 .then(TaskRequest(
 id: 'upload',
 worker: NativeWorker.httpUpload(
 url: 'https://backup.example.com/upload',
 filePath: '/tmp/photo_compressed.jpg',
 ),
 ))
 .named('photo-backup')
 .enqueue();
```
</details>

---

## Listen to task events

```dart
NativeWorkManager.events.listen((event) {
  if (event.isStarted) {
    print('▶ ${event.taskId} started (${event.workerType})');
    return;
  }
  if (event.success) {
    print('✅ ${event.taskId} — ${event.resultData}');
  } else {
    print('❌ ${event.taskId} — ${event.message}');
  }
});
```

---

## Documentation

| Guide | Description |
|---|---|
| [Getting Started](doc/GETTING_STARTED.md) | Full setup walkthrough |
| [API Reference](doc/API_REFERENCE.md) | All public types and methods |
| [Android Setup Guide](doc/ANDROID_SETUP.md) | DartWorker killed-app persistence |
| [iOS Setup Guide](doc/IOS_SETUP_GUIDE.md) | BGTaskScheduler details |
| [Migration from workmanager](doc/MIGRATION_GUIDE.md) | Switch in under 10 minutes |
| [Security](doc/SECURITY.md) | SSRF, path traversal, data redaction |
| [native_workmanager_gen](https://pub.dev/packages/native_workmanager_gen) | Code generator for type-safe DartWorker callbacks |

---

## Support

- [GitHub Issues](https://github.com/brewkits/native_workmanager/issues) — bugs and feature requests
- [Discussions](https://github.com/brewkits/native_workmanager/discussions) — questions and community help

---

MIT License · Made by [BrewKits](https://brewkits.dev)

*Found this useful? A ⭐ on [GitHub](https://github.com/brewkits/native_workmanager) helps others discover it.*

native_workmanager

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README