native_workmanager #

Native background task manager for Flutter with zero Flutter Engine overhead.

Flutter background task manager with native workers and task chains.

✨ Key Features #

Zero Flutter Engine Overhead: Native workers execute I/O tasks without loading the Flutter Engine
Task Chains: Automate multi-step workflows (Download → Process → Upload) with built-in dependency management
11 Built-in Workers: HTTP, File operations, Compression, Crypto, Image processing
Hybrid Architecture: Choose native workers for I/O or Dart workers for complex logic
Production Ready: 808 passing tests, comprehensive documentation, iOS 12.0+ and Android API 21+ support

🚀 Quick Start #

Step 1: Install

flutter pub add native_workmanager

Step 2: Initialize

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

Step 3: Schedule a Task

Option A: Simple HTTP Sync (Native Worker)

// Starts hourly API sync without Flutter Engine overhead
await NativeWorkManager.enqueue(
  taskId: 'sync',
  trigger: TaskTrigger.periodic(Duration(hours: 1)),
  worker: NativeWorker.httpSync(  // ← Native worker
    url: 'https://api.example.com/sync',
    method: HttpMethod.post,
  ),
);
// ✓ Task runs every hour, even when app is closed
// ✓ No Flutter Engine overhead

Option B: Complex Dart Logic (Dart Worker)

// For tasks requiring custom Dart code or packages
await NativeWorkManager.enqueue(
  taskId: 'process',
  trigger: TaskTrigger.oneTime(),
  worker: DartWorker(callbackId: 'complexLogic'),  // ← Dart worker
);
// ✓ Access to all Dart packages
// ✓ Full Flutter/Dart ecosystem support

Tasks are registered with the OS and survive app restarts, phone reboots, and force-quits.

Complete getting started guide →

🔄 Migrating from workmanager? #

Good news: ~90% API compatibility, most code stays the same!

Quick Migration Checklist #

❌ Replace Workmanager.registerPeriodicTask with NativeWorkManager.enqueue
❌ Update task trigger syntax (same logic, different API)
❌ Replace callback with DartWorker(callbackId) or use native workers
❌ Test on both iOS and Android (should work immediately!)

Common Migration Pattern #

Before (workmanager):

Workmanager.registerPeriodicTask(
  'myTask',
  'api_sync',
  frequency: Duration(hours: 1),
);

After (native_workmanager):

// Upgrade to native worker
NativeWorkManager.enqueue(
  taskId: 'myTask',
  trigger: TaskTrigger.periodic(Duration(hours: 1)),
  worker: NativeWorker.httpSync(  // ← Native HTTP worker
    url: 'https://api.example.com/sync',
  ),
);

Result: Same functionality, zero Flutter Engine overhead for I/O tasks.

Full migration guide → | Migration tool →

🎯 Choose Your Use Case #

📊 I need periodic API sync #

→ Use Native Workers (zero Flutter Engine overhead)

No Flutter Engine overhead
Minimal battery impact
See example →

📁 I need file uploads with retry #

→ Use HttpUploadWorker with Task Chains

Built-in retry logic
Progress tracking
Automatic cleanup
See example →

🖼️ I need photo backup pipeline #

→ Use Task Chains (Download → Compress → Upload)

Sequential or parallel execution
Automatic dependency management
Failure isolation
See example →

🔧 I have complex Dart logic #

→ Use DartWorker with autoDispose

Full Flutter Engine access
All Dart packages available
Smart memory management
See example →

See all 8 use cases →

💡 Why native_workmanager? #

Unique Features #

1. Native Workers

Execute I/O tasks without spawning Flutter Engine
11 Built-in Workers: HTTP (request, upload, download, sync), Files (compress, decompress, copy, move, delete), Image processing, Crypto (hash, encrypt, decrypt)
Extensible with custom Kotlin/Swift workers

2. Task Chains

Automate multi-step workflows: A → B → C or A → [B1, B2, B3] → D
Built-in dependency management
Automatic retry and failure handling
Data passing between steps

3. Hybrid Execution Model

Choose per-task: Native workers (I/O) or Dart workers (complex logic)
autoDispose flag for fine-grained engine lifecycle control
Best of both worlds

4. Cross-Platform Consistency

Unified API across Android and iOS
Platform feature parity
Built on kmpworkmanager for reliability

See FAQ →

🖥️ Platform Support #

Platform	Status	Min Version	Key Limitation
Android	✅ Supported	API 21 (5.0+)	Doze mode may defer tasks
iOS	✅ Supported	iOS 12.0+	30-second execution limit

iOS: 30-Second Execution Limit ⚠️ #

Background tasks on iOS must complete in 30 seconds. For longer tasks:

Solutions:

✅ Use task chains - Split work into 30-second chunks
✅ Use native workers - Faster than Dart workers (no engine overhead)
✅ Use Background URLSession - For large file transfers (no time limit)
⚠️ Consider foreground services for truly long tasks

Example:

// ❌ Won't work: Takes 90 seconds
await downloadLargeFile();  // 60sec
await processFile();        // 30sec

// ✅ Works: Split into chain (each <30sec)
await NativeWorkManager.beginWith(
  TaskRequest(id: 'download', worker: HttpDownloadWorker(...)),  // 20sec
).then(
  TaskRequest(id: 'process', worker: ImageProcessWorker(...)),   // 15sec
).enqueue();

Read iOS background task guide →

Android: Doze Mode & Battery Optimization #

Android 6+ may defer tasks in Doze mode. Use constraints to ensure execution:

await NativeWorkManager.enqueue(
  taskId: 'important-sync',
  trigger: TaskTrigger.periodic(Duration(hours: 1)),
  worker: NativeWorker.httpSync(url: 'https://api.example.com/sync'),
  constraints: Constraints(
    requiresNetwork: true,         // Wait for network
    requiresCharging: true,        // Wait for charging (optional)
    requiresBatteryNotLow: true,   // Skip if battery low
  ),
);

Read Android optimization guide →

📚 Complete Documentation #

🚀 Start Here #

Quick Start (3 min) - Get running fast
API Reference - Complete API docs
FAQ - Common questions answered

📖 Learn by Example #

Real-World Use Cases (8 examples)
- Periodic API Sync
- File Upload with Retry
- Background Cleanup
- Photo Auto-Backup
- Hybrid Dart/Native Workflows
- Task Chain Processing
- And more...

🔧 Build It Right #

Security Policy - Report vulnerabilities, best practices
Production Deployment - Launch with confidence
Platform Consistency - iOS vs Android differences

🎓 Go Deep #

Custom Native Workers - Write Kotlin/Swift workers
Task Chains & Workflows - Complex automations
iOS Background Limits - 30-second workarounds

❓ FAQ #

Q: Will my task run if the app is force-closed? A: Yes! Tasks are registered with the OS (Android WorkManager / iOS BGTaskScheduler), not your Flutter app.

Q: How much memory does a task actually use? A: Native workers execute without Flutter Engine overhead. Dart workers require the full Flutter runtime. Actual memory usage depends on worker type and task complexity.

Q: Can I chain 100 tasks together? A: Yes, but on iOS each task in the chain must complete within 30 seconds. Use native workers for speed.

Q: What happens if a task in a chain fails? A: The chain stops. Subsequent tasks are cancelled. You can use retry policies to handle failures.

Q: Is this compatible with workmanager? A: ~90% compatible. Most code works with minor syntax changes. See migration guide.

Q: Can I use this for location tracking? A: Background tasks are for periodic work, not continuous tracking. For location, use geolocator with background modes.

See full FAQ →

🔌 Popular Integrations #

Dio - HTTP client for complex requests
Hive - Local database sync
Firebase - Analytics & Crashlytics
Sentry - Error tracking in background tasks

See all integrations →

📊 Production Ready #

Security: No critical vulnerabilities
Tests: 808 unit tests passing
Coverage: All 11 native workers tested
Platforms: iOS 12.0+ and Android API 21+

🤝 Community & Support #

💬 GitHub Discussions - Ask questions, share use cases
🐛 Issue Tracker - Report bugs
📧 Email: support@brewkits.dev

Found a Bug? #

Search existing issues
Create new issue with:
- Flutter version (flutter --version)
- Platform (iOS/Android)
- Minimal reproducible example

🤝 Contributing #

We welcome contributions! See CONTRIBUTING.md for:

How to report bugs
How to request features
How to submit pull requests
Coding standards

🙏 Acknowledgments #

Built with ❤️ using platform-native APIs:

Android: WorkManager - Google's official background task library
iOS: BGTaskScheduler - Apple's background task framework
Shared Core: kmpworkmanager - Cross-platform worker orchestration

Inspired by Android WorkManager and iOS BackgroundTasks best practices.

📞 Support & Contact #

Need help?

🌐 Website: brewkits.dev
🐛 Issues: GitHub Issues
📧 Email: datacenter111@gmail.com

Links:

📄 License #

Licensed under the MIT License - see LICENSE file for details.

Author: Nguyễn Tuấn Việt • BrewKits

⭐ If this library helps your Flutter app, please star the repo!

native_workmanager 1.0.2
native_workmanager: ^1.0.2 copied to clipboard

Metadata

native_workmanager #

✨ Key Features #

🚀 Quick Start #

🔄 Migrating from workmanager? #

Quick Migration Checklist #

Common Migration Pattern #

🎯 Choose Your Use Case #

📊 I need periodic API sync #

📁 I need file uploads with retry #

🖼️ I need photo backup pipeline #

🔧 I have complex Dart logic #

💡 Why native_workmanager? #

Unique Features #

🖥️ Platform Support #

iOS: 30-Second Execution Limit ⚠️ #

Android: Doze Mode & Battery Optimization #

📚 Complete Documentation #

🚀 Start Here #

📖 Learn by Example #

🔧 Build It Right #

🎓 Go Deep #

❓ FAQ #

🔌 Popular Integrations #

📊 Production Ready #

🤝 Community & Support #

Found a Bug? #

🤝 Contributing #

🙏 Acknowledgments #

📞 Support & Contact #

📄 License #

← Metadata

Publisher

Weekly Downloads

Metadata

Documentation

License

Dependencies

More

native_workmanager 1.0.2 native_workmanager: ^1.0.2 copied to clipboard

Metadata

native_workmanager #

✨ Key Features #

🚀 Quick Start #

🔄 Migrating from workmanager? #

Quick Migration Checklist #

Common Migration Pattern #

🎯 Choose Your Use Case #

📊 I need periodic API sync #

📁 I need file uploads with retry #

🖼️ I need photo backup pipeline #

🔧 I have complex Dart logic #

💡 Why native_workmanager? #

Unique Features #

🖥️ Platform Support #

iOS: 30-Second Execution Limit ⚠️ #

Android: Doze Mode & Battery Optimization #

📚 Complete Documentation #

🚀 Start Here #

📖 Learn by Example #

🔧 Build It Right #

🎓 Go Deep #

❓ FAQ #

🔌 Popular Integrations #

📊 Production Ready #

🤝 Community & Support #

Found a Bug? #

🤝 Contributing #

🙏 Acknowledgments #

📞 Support & Contact #

📄 License #

← Metadata

Publisher

Weekly Downloads

Metadata

Documentation

License

Dependencies

More

native_workmanager 1.0.2
native_workmanager: ^1.0.2 copied to clipboard