offline_sync_queue

A powerful, robust, and highly responsive offline-first sync engine for Flutter. Automatically queue API calls or local actions when the user loses internet connection, and seamlessly sync them in the background the moment the connection is restored.

Features

📡 Auto Network Detection & Heartbeat: Listens to connectivity changes with built-in DNS host lookup validation for 100% reliable online/offline detection across physical devices and simulators.
💾 Local Persistence: Safely stores queued actions locally using shared_preferences so data is preserved even if the app restarts or crashes while offline.
⚡ Fully Reactive Streams: Exposes isOnlineStream and queueStream so your UI updates in real-time without extra boilerplate.
🚀 Drop-in Execution: Simple, intuitive API (addJob, startSync) to make any network call offline-ready.

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  offline_sync_queue: ^0.0.2

Then run:

flutter pub get

Usage

1. Initialize Sync Engine

In your app initialization (e.g., main.dart or state controller), start the sync engine with your custom job processor function:

import 'package:flutter/material.dart';
import 'package:offline_sync_queue/offline_sync_queue.dart';

void main() {
  // Initialize the sync processor
  OfflineSyncQueue().startSync((Map<String, dynamic> job) async {
    try {
      print("Processing job: ${job['action']} with data: ${job['payload']}");
      // Perform your API call here
      // Return true to remove the job from the local queue upon success
      return true;
    } catch (e) {
      // Return false to retain the job in the queue for retrying later
      return false;
    }
  });

  runApp(const MyApp());
}

2. Queueing Jobs

Whenever a user triggers an action (such as creating a post, submitting a form, or liking a photo), call addJob. If the user is offline, offline_sync_queue automatically saves it locally:

await OfflineSyncQueue().addJob({
  'action': 'create_post',
  'payload': {
    'title': 'Hello World',
    'content': 'This post was created while offline!',
  },
  'timestamp': DateTime.now().toIso8601String(),
});

3. Reactive UI Integration

You can easily build real-time responsive UIs using the reactive streams provided by OfflineSyncQueue:

class NetworkStatusWidget extends StatelessWidget {
  const NetworkStatusWidget({super.key});

  @override
  Widget build(BuildContext context) {
    return StreamBuilder<bool>(
      stream: OfflineSyncQueue().isOnlineStream,
      initialData: OfflineSyncQueue().isOnline,
      builder: (context, snapshot) {
        final isOnline = snapshot.data ?? false;
        return Chip(
          avatar: Icon(isOnline ? Icons.wifi : Icons.wifi_off),
          label: Text(isOnline ? 'Online' : 'Offline'),
          backgroundColor: isOnline ? Colors.green : Colors.red,
        );
      },
    );
  }
}

Demo

Check out the example/ folder for a fully working demonstration of the package.

License

Author

Developed By Shahzain Baloch