Package selection guidance compiled from public package information, community data, and project usage.
workmanager_web provides an experimental web implementation of the workmanager package, enabling background task execution on Flutter Web apps using Service Workers and Web Workers. It allows scheduling and running tasks even when the app is not actively in use, mimicking native background processing capabilities. This package is designed to support periodic and one-time tasks in web environments where traditional background execution is limited.
Use cases
Scheduling periodic data syncs
Running background tasks after app closure
Implementing push notification handling
Executing long-running operations without blocking UI
Supporting offline-first applications
Key features
Service Worker integration
Web Worker-based task execution
Periodic and one-time task scheduling
Experimental web compatibility
Minimal runtime overhead
Suitable for
Flutter Web developers needing background tasks
Apps requiring scheduled maintenance
Offline-capable web applications
Developers testing background workflows on web
Considerations
Experimental status with potential instability
Limited browser support for Service Workers
No guaranteed execution timing on all browsers
Requires HTTPS in production
Not suitable for critical time-sensitive operations
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
Flutter Workmanager
Execute Dart code in the background, even when your app is closed (Android and iOS). On macOS, background tasks run while the app is running or backgrounded and the Mac is awake. Perfect for data sync, file uploads, and periodic maintenance tasks.
⚠️ Experimental web support now exists via workmanager_web (Service
Worker + Web Worker based background execution). See the
Web (experimental) page and the
package README for honest limitations and how to
test it in Chrome.
→ Troubleshooting Guide - Why tasks stop after app close (OEM battery optimization, constraints, verification)
🎯 Use Cases
Background tasks are perfect for:
Sync data from API - Keep your app's data fresh
Upload files in background - Reliable file uploads
Clean up old data - Remove old files and cache
Fetch notifications - Check for new messages
Database maintenance - Optimize and clean databases
⏱ Long-Running Tasks (Android)
For work that takes longer than the regular background execution window (bulk
uploads/downloads, ML processing), Android tasks can run as a foreground
service with a persistent notification. Pass a foregroundServiceConfig to
registerOneOffTask or registerPeriodicTask:
awaitWorkmanager().registerOneOffTask(
"upload-task",
"upload_files",
foregroundServiceConfig: ForegroundServiceConfig(
notificationTitle: "Uploading files",
notificationText: "Your files are being uploaded",
),
);
cancelByUniqueName, cancelByTag and cancelAll stop the WorkManager worker
immediately, but the Dart callback that is currently running keeps executing
unless it reacts to the stop. Pass an onTaskStopped handler to executeTask
inside your callbackDispatcher to be notified when a running task is stopped
before it finishes:
@pragma('vm:entry-point')
voidcallbackDispatcher() {
Workmanager().executeTask(
(taskName, inputData) async {
returntrue;
},
onTaskStopped: (taskName, stopReason) async {
// Mark the task as cancelled / persist state, then return promptly.
},
);
}
The handler receives the task name and the WorkManager stop reason
(cancelledByApp, timeout, preempt, ...); on Android < 12 the reason is
StopReason.unknown. Android-only — iOS has no way to stop a running task.
See the Customization guide
for details.
