native_workmanager library

Native background task manager for Flutter.

Zero Flutter Engine overhead. Built on Kotlin Multiplatform.

Quick Start

import 'package:native_workmanager/native_workmanager.dart';

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

// Schedule a periodic sync
await NativeWorkManager.enqueue(
  taskId: 'sync',
  trigger: TaskTrigger.periodic(Duration(hours: 1)),
  worker: NativeWorker.httpSync(url: 'https://api.example.com/sync'),
  constraints: Constraints.networkRequired,
);

Features

Native Workers: Run background tasks without Flutter Engine (~2MB vs ~50MB RAM)
Task Chains: Complex workflows (A → B → C)
Auto iOS Config: Reads Info.plist automatically
Built-in Workers: HTTP (request, upload, download, sync), Files (compress, decompress, file system, shared storage), Image processing, Cryptography (hash, encrypt, decrypt), PDF (merge, compress, images-to-PDF), WebSocket (Android)

See NativeWorkManager for full documentation.

Classes

AuthConfig: Authentication configuration for HTTP workers.
BatteryLowTrigger: Execute when battery IS low (Android only).
BatteryOkayTrigger: Execute when battery is NOT low (Android only).
CompressionResult: Result data from FileCompressionWorker.
Constraints: Constraints that must be met before a task can run.
ContentUriTrigger: Execute when a content URI changes (Android only).
CryptoDecryptWorker: Crypto worker configuration for file decryption.
CryptoEncryptWorker: Crypto worker configuration for file encryption.
CryptoHashWorker: Crypto worker configuration for file hashing.
CryptoResult: Result data from CryptoHashWorker, CryptoEncryptWorker, or CryptoDecryptWorker operations.
CustomNativeWorker: Custom native worker configuration.
DartWorker: Dart callback worker for custom logic (requires Flutter Engine).
DartWorkerInternal: Internal DartWorker with callback handle.
DecompressionResult: Result data from FileDecompressionWorker.
DeviceIdleTrigger: Execute when device is idle (Android only).
DownloadFileOutcome: Per-file outcome inside ParallelDownloadResult.files.
DownloadResult: Typed result helpers for built-in workers.
EnqueueRequest: A single task request for use with NativeWorkManager.enqueueAll.
ExactTrigger: Execute at an exact time.
FileCompressionWorker: File compression worker configuration.
FileDecompressionWorker: File decompression worker configuration.
FileSystemCopyWorker: File system worker configuration for copy operation.
FileSystemDeleteWorker: File system worker configuration for delete operation.
FileSystemListWorker: File system worker configuration for list operation.
FileSystemMkdirWorker: File system worker configuration for mkdir operation.
FileSystemMoveWorker: File system worker configuration for move operation.
FileSystemResult: Result data from file system workers (FileSystemCopyWorker, FileSystemMoveWorker, etc.).
GraphExecution: Handle returned by NativeWorkManager.enqueueGraph.
GraphResult: Result of a TaskGraph execution.
HeaderMiddleware: Middleware that adds HTTP headers to all matching requests.
HttpDownloadWorker: HTTP download worker configuration.
HttpRequestResult: Result data from HttpRequestWorker.
HttpRequestWorker: HTTP request worker configuration.
HttpSyncWorker: HTTP sync worker configuration.
HttpUploadWorker: HTTP upload worker configuration.
ImageProcessResult: Result data from ImageProcessWorker.
ImageProcessWorker: Image processing worker configuration.
LoggingMiddleware: Middleware that POSTs task execution metadata to a custom endpoint after each task completes (success or failure).
Middleware: Base class for all background task middleware.
MoveToSharedStorageWorker: Move a file from app-private storage to a shared / public location.
MultiUploadWorker: Upload multiple files in a single multipart/form-data HTTP request.
NativeWorker: Built-in native workers that run WITHOUT Flutter Engine.
NativeWorkManager
ObservabilityConfig: Configuration for built-in observability hooks.
ObservabilityDispatcher: Internal dispatcher that routes events/progress to ObservabilityConfig.
OfflineQueue: A persistent, ordered queue of background tasks that are retried automatically when network is available.
OfflineRetryPolicy: Retry policy for OfflineQueue tasks.
OneTimeTrigger: Execute once after an optional delay.
ParallelDownloadResult: Result data from ParallelHttpDownloadWorker.
ParallelHttpDownloadWorker: Parallel chunked HTTP download worker configuration.
ParallelHttpUploadWorker: Parallel multi-file HTTP upload worker configuration.
ParallelUploadResult: Result data from ParallelHttpUploadWorker.
PdfCompressWorker: Re-render a PDF at reduced quality to shrink its file size.
PdfFromImagesWorker: Convert a list of image files into a PDF (one image per page).
PdfMergeWorker: Merge multiple PDF files into a single output PDF.
PerformanceEvent: A performance event record.
PerformanceMonitor: Performance monitoring utilities for native_workmanager.
PerformanceStatistics: Performance statistics summary.
PeriodicTrigger: Execute periodically at a fixed interval.
QueueEntry: An entry in an OfflineQueue.
RemoteConfigMiddleware: Middleware that injects remote configuration values into worker configs at execution time.
RemoteTriggerRule: A rule for matching and executing a remote trigger.
RequestSigning: HMAC-based request signing configuration for HTTP workers.
StorageLowTrigger: Execute when storage is low (Android only).
SystemError: Represents a critical system-level error on the native side.
TaskChainBuilder: Builder for creating task chains (A -> B -> C workflows).
TaskEvent: Event emitted for task lifecycle transitions (started, completed, failed).
TaskGraph: A directed acyclic graph (DAG) of background tasks.
TaskHandler: A controller for a specific background task.
TaskMetrics: Metrics for a single task execution.
TaskNode: A node in a TaskGraph.
TaskProgress: Progress update during task execution.
TaskProgressBuilder: A widget that builds itself based on the latest TaskProgress of a task.
TaskProgressCard: A pre-styled Material 3 card that displays the progress of a background task.
TaskRecord: Record from the persistent task store.
TaskRequest: A single task request in a chain.
TaskTrigger: Defines when a task should be executed.
TokenRefreshConfig: Configuration for automatic token refresh.
UploadFile: Represents a single file in a multi-file upload.
UploadFileOutcome: Per-file outcome inside ParallelUploadResult.files.
UploadResult: Result data from HttpUploadWorker.
WebSocketWorker: Connect to a WebSocket endpoint, send messages, and receive responses.
WindowedTrigger: Execute within a time window.
Worker: Base class for all worker configurations.
WorkerCallback: Annotation for the native_workmanager_gen code generator.
WorkerTypeStatistics: Statistics for a specific worker type.
WorkManagerLogger: Type-safe delegate for forwarding task events to third-party SDKs.

Enums

BackoffPolicy: Backoff policy for retry behavior when task fails.
BGTaskType: iOS background task type selection (iOS 13.0+ only).
CompressionLevel: Compression levels for file compression.
DuplicatePolicy: What to do if the destination file already exists.
EncryptionAlgorithm: Encryption algorithms supported by CryptoWorker.
ExactAlarmIOSBehavior: iOS-specific behavior for exact time alarms.
ExistingTaskPolicy: Policy for handling existing tasks with the same ID.
FileOperation: File system operations.
ForegroundServiceType: Android 14+ foreground service type for heavy tasks.
HashAlgorithm: Hash algorithms supported by CryptoWorker.
HttpMethod: HTTP methods for network workers.
ImageFormat: Image output formats.
NativeWorkManagerError: Typed error codes for failed TaskEvents.
PdfPageSize: PDF page size for PdfFromImagesWorker.
PerformanceEventType: Performance event types.
QoS: Quality of Service (QoS) priority for task execution.
RemoteTriggerSource: Sources for remote triggers.
ScheduleResult: Result of scheduling a task.
SharedStorageType: Target shared storage location for MoveToSharedStorageWorker.
SystemConstraint: System-level constraints for task execution (Android only).
TaskStatus: Current status of a task.

Extension Types

TaskId: A compile-time–typed wrapper around a task ID string.

Extensions

TaskProgressExtensions on TaskProgress: Helper extensions for displaying TaskProgress information.

Functions

enqueueTaskGraph(TaskGraph graph) → Future<GraphExecution>: Enqueue a TaskGraph for execution.
registerDevToolsExtensions() → void

Typedefs

DartWorkerCallback = Future<bool> Function(Map<String, dynamic>? input): Marks a top-level function as a DartWorker callback.

native_workmanager library

Quick Start

Features

Classes

Enums

Extension Types

Extensions

Functions

Typedefs

native_workmanager package

native_workmanager library