📦 riverpod_offline_sync

A production-ready offline-first sync engine for Flutter with Riverpod state management, queue orchestration, conflict resolution, Firebase integration, retry handling, connectivity monitoring, and built-in offline UI components.

pub version license Flutter

Table of Contents

✨ Features

  • 🔄 Bi-directional sync (push + pull)
  • 📦 Persistent offline queue (Hive)
  • ⚡ Concurrent queue processing
  • 🔁 Smart retry with exponential backoff
  • 🔌 Connectivity-aware synchronization
  • 📶 WiFi-only sync mode
  • 🧠 Conflict resolution strategies
  • 🧾 Idempotency protection
  • 📊 Sync metrics & analytics
  • 🛠 Debug inspection tools
  • 🎨 Built-in UI widgets
  • 🔥 Full Firebase integrations (Firestore, Storage, Auth)
  • 🧩 Riverpod integration
  • 📱 Offline-first architecture
  • 🚀 Queue survives app restarts
  • 🎯 Upload pause / resume / cancel
  • 📈 Real-time sync progress streams
  • 🔒 Production-ready sync orchestration

🆕 What's New in v1.0.0

  • 📊 Queue Statistics API — Get detailed queue insights (pending/failed/retrying counts, age, breakdowns)
  • 👁️ Sync Observer System — Listen to sync events for analytics and monitoring
  • 🎯 OfflineSyncScope Widget — Simplified initialization with loading states
  • 🔧 Improved Queue Trimming — Smart priority-based queue management
  • 🆔 UUID-based IDs — Better collision prevention for queue items
  • 📈 Enhanced Progress Tracking — Percentage-based upload progress
  • 🔌 Better Connectivity Handling — Safe disposal and improved WiFi detection
  • 🛡️ Conflict Detector Ignored Fields — Skip timestamp fields in conflict detection

Dependencies

Add the following to your pubspec.yaml:

dependencies:
  riverpod_offline_sync: ^1.0.0
  flutter_riverpod: ^2.5.0
  firebase_core: ^2.24.0
  cloud_firestore: ^4.17.0
  firebase_storage: ^11.6.0
  firebase_auth: ^4.17.0
  hive_flutter: ^1.1.0
  connectivity_plus: ^5.0.0
  synchronized: ^3.1.0
  http: ^1.1.0

Then run:

flutter pub get

Quick Start with Firebase

1. Complete Setup in main()

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:riverpod_offline_sync/riverpod_offline_sync.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:cloud_firestore/cloud_firestore.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize Firebase
  await Firebase.initializeApp();

  // Enable Firestore native offline persistence
  await FirebaseFirestore.instance.settings =
      const Settings(persistenceEnabled: true);

  // Initialize offline sync layer
  await OfflineSyncLayer.instance.initialize(
    config: const SyncConfig(
      autoSyncOnReconnect: true,
      syncImmediately: true,
      maxConcurrentOperations: 3,
      enableMetrics: true,
      enableDebugLogging: false,
    ),
  );

  // Register ALL operation handlers
  _registerHandlers();

  runApp(const ProviderScope(child: MyApp()));
}

2. Register All Operation Handlers

void _registerHandlers() {
  final sync = OfflineSyncLayer.instance;

  // ✅ CREATE / SET document handler
  sync.registerOperationHandler('firestore_set', (data) async {
    await FirebaseFirestore.instance
        .collection(data['collection'])
        .doc(data['docId'])
        .set(Map<String, dynamic>.from(data['payload']));
  });

  // ✅ UPDATE document handler
  sync.registerOperationHandler('firestore_update', (data) async {
    await FirebaseFirestore.instance
        .collection(data['collection'])
        .doc(data['docId'])
        .update(Map<String, dynamic>.from(data['payload']));
  });

  // ✅ DELETE document handler
  sync.registerOperationHandler('firestore_delete', (data) async {
    await FirebaseFirestore.instance
        .collection(data['collection'])
        .doc(data['docId'])
        .delete();
  });

  // ✅ Batch write handler
  sync.registerOperationHandler('firestore_batch', (data) async {
    final batch = FirebaseFirestore.instance.batch();
    final writes = List<Map<String, dynamic>>.from(data['writes']);

    for (final write in writes) {
      final docRef = FirebaseFirestore.instance
          .collection(write['collection'])
          .doc(write['docId']);

      switch (write['type']) {
        case 'set':
          batch.set(docRef, write['data']);
          break;
        case 'update':
          batch.update(docRef, write['data']);
          break;
        case 'delete':
          batch.delete(docRef);
          break;
      }
    }

    await batch.commit();
  });

  // ✅ Custom REST API handler
  sync.registerOperationHandler('api_request', (data) async {
    final response = await http.post(
      Uri.parse(data['url']),
      body: data['body'],
      headers: data['headers'],
    );

    if (response.statusCode != 200) {
      throw Exception('API request failed: ${response.statusCode}');
    }

    return response.body;
  });

  // ✅ Analytics handler (low priority)
  sync.registerOperationHandler('analytics', (data) async {
    await AnalyticsService.trackEvent(
      data['event_name'],
      properties: data['properties'],
    );
  });
}

3. Wrap Your App

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Offline-First App',
      home: ConnectivityBanner(
        child: OfflineToast(
          child: HomePage(),
        ),
      ),
    );
  }
}

4. Submit Offline Operations

// ✅ CREATE document (works offline)
Future<void> createUser(String userId, String name, String email) async {
  await OfflineSyncLayer.instance.submitOperation(
    category: 'firestore_set',
    priority: QueuePriority.high.value,
    idempotencyKey: 'set_user_${userId}_${DateTime.now().millisecondsSinceEpoch}',
    data: {
      'collection': 'users',
      'docId': userId,
      'payload': {
        'name': name,
        'email': email,
        'createdAt': DateTime.now().toIso8601String(),
        'updatedAt': DateTime.now().toIso8601String(),
      },
    },
  );
}

// ✅ UPDATE document (works offline)
Future<void> updateUser(String userId, Map<String, dynamic> updates) async {
  await OfflineSyncLayer.instance.submitOperation(
    category: 'firestore_update',
    priority: QueuePriority.normal.value,
    idempotencyKey: IdempotencyKey.generate(),
    data: {
      'collection': 'users',
      'docId': userId,
      'payload': {
        ...updates,
        'updatedAt': DateTime.now().toIso8601String(),
      },
    },
  );
}

// ✅ DELETE document (works offline)
Future<void> deleteUser(String userId) async {
  await OfflineSyncLayer.instance.submitOperation(
    category: 'firestore_delete',
    priority: QueuePriority.high.value,
    idempotencyKey: 'delete_user_${userId}_${DateTime.now().millisecondsSinceEpoch}',
    data: {
      'collection': 'users',
      'docId': userId,
    },
  );
}

Complete Firebase Integration

Firestore Operations

class OfflineFirestoreService {
  static Future<void> submitOperation({
    required String category,
    required Map<String, dynamic> data,
    QueuePriority priority = QueuePriority.normal,
    String? customIdempotencyKey,
  }) async {
    await OfflineSyncLayer.instance.submitOperation(
      category: category,
      priority: priority.value,
      idempotencyKey: customIdempotencyKey ?? IdempotencyKey.generate(),
      data: data,
    );
  }

  static Future<void> setDocument({
    required String collection,
    required String docId,
    required Map<String, dynamic> data,
  }) async {
    await submitOperation(
      category: 'firestore_set',
      priority: QueuePriority.high,
      data: {'collection': collection, 'docId': docId, 'payload': data},
    );
  }

  static Future<void> updateDocument({
    required String collection,
    required String docId,
    required Map<String, dynamic> updates,
  }) async {
    await submitOperation(
      category: 'firestore_update',
      priority: QueuePriority.normal,
      data: {'collection': collection, 'docId': docId, 'payload': updates},
    );
  }

  static Future<void> deleteDocument({
    required String collection,
    required String docId,
  }) async {
    await submitOperation(
      category: 'firestore_delete',
      priority: QueuePriority.high,
      data: {'collection': collection, 'docId': docId},
    );
  }

  static Future<void> batchWrite({
    required List<Map<String, dynamic>> operations,
  }) async {
    await submitOperation(
      category: 'firestore_batch',
      priority: QueuePriority.high,
      data: {'writes': operations},
    );
  }
}

// Usage
await OfflineFirestoreService.setDocument(
  collection: 'products',
  docId: 'prod_001',
  data: {'name': 'Laptop', 'price': 999},
);

await OfflineFirestoreService.updateDocument(
  collection: 'products',
  docId: 'prod_001',
  updates: {'price': 899},
);

await OfflineFirestoreService.batchWrite(
  operations: [
    {'type': 'update', 'collection': 'products', 'docId': 'prod_001', 'data': {'stock': 5}},
    {'type': 'set', 'collection': 'orders', 'docId': 'order_001', 'data': {'productId': 'prod_001'}},
  ],
);

Firebase Storage Uploads

final storageQueue = StorageQueue();

// Upload a file with full queue support
Future<void> uploadUserPhoto(File file, String userId) async {
  final idempotencyKey = IdempotencyKey.generate();

  await storageQueue.uploadFile(
    file: file,
    path: 'uploads/$userId/photo.jpg',
    idempotencyKey: idempotencyKey,
    onProgress: (percentage) {
      print('Upload progress: ${(percentage * 100).toStringAsFixed(1)}%');
    },
  );

  // Control the upload
  storageQueue.pauseUpload(idempotencyKey);
  storageQueue.resumeUpload(idempotencyKey);
  storageQueue.cancelUpload(idempotencyKey);
}

// Upload multiple files
Future<void> uploadMultipleFiles(List<File> files, String userId) async {
  for (final file in files) {
    await storageQueue.uploadFile(
      file: file,
      path: 'uploads/$userId/${DateTime.now().millisecondsSinceEpoch}.jpg',
      idempotencyKey: IdempotencyKey.generate(),
    );
  }
}

Firebase Auth Persistence

final auth = AuthPersistence();

// Sign in (works offline - stores credentials)
await auth.signInWithEmail('email@example.com', 'password');

// Check auth state
final user = auth.currentUser;
if (user != null) {
  print('Signed in as: ${user.email}');
}

// Set persistence type
await auth.setPersistence(AuthPersistenceType.local);   // Keep logged in
await auth.setPersistence(AuthPersistenceType.session); // Until app closes
await auth.setPersistence(AuthPersistenceType.none);    // Never persist

Real-time Firestore + Offline Queue

// Provider for real-time Firestore data
final usersProvider = StreamProvider.autoDispose<List<User>>((ref) {
  return FirebaseFirestore.instance
      .collection('users')
      .snapshots()
      .map((snapshot) => snapshot.docs
          .map((doc) => User.fromFirestore(doc))
          .toList());
});

class UserListPage extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final usersAsync = ref.watch(usersProvider);
    final pendingCount = ref.watch(pendingItemsCountProvider).valueOrNull ?? 0;
    final isSyncing = ref.watch(isSyncingProvider);

    return Scaffold(
      appBar: AppBar(
        title: Text('Users'),
        actions: [
          if (pendingCount > 0)
            Stack(
              children: [
                Icon(Icons.sync),
                Positioned(
                  right: 0,
                  top: 0,
                  child: Container(
                    padding: EdgeInsets.all(2),
                    decoration: BoxDecoration(
                      color: Colors.red,
                      borderRadius: BorderRadius.circular(10),
                    ),
                    constraints: BoxConstraints(minWidth: 16, minHeight: 16),
                    child: Text(
                      '$pendingCount',
                      style: TextStyle(color: Colors.white, fontSize: 10),
                      textAlign: TextAlign.center,
                    ),
                  ),
                ),
              ],
            ),
        ],
      ),
      body: Stack(
        children: [
          usersAsync.when(
            data: (users) => ListView.builder(
              itemCount: users.length,
              itemBuilder: (context, index) {
                return ListTile(
                  title: Text(users[index].name),
                  subtitle: Text(users[index].email),
                  trailing: IconButton(
                    icon: Icon(Icons.delete),
                    onPressed: () async {
                      await OfflineFirestoreService.deleteDocument(
                        collection: 'users',
                        docId: users[index].id,
                      );
                    },
                  ),
                );
              },
            ),
            loading: () => Center(child: CircularProgressIndicator()),
            error: (err, stack) => Center(child: Text('Error: $err')),
          ),
          if (isSyncing)
            Positioned(
              top: 0,
              left: 0,
              right: 0,
              child: LinearProgressIndicator(),
            ),
        ],
      ),
      floatingActionButton: FloatingActionButton(
        child: Icon(Icons.add),
        onPressed: () async {
          await OfflineFirestoreService.setDocument(
            collection: 'users',
            docId: 'user_${DateTime.now().millisecondsSinceEpoch}',
            data: {
              'name': 'New User',
              'email': 'new@example.com',
              'createdAt': DateTime.now().toIso8601String(),
            },
          );
        },
      ),
    );
  }
}

New in v1.0.0

Queue Statistics API

// Get comprehensive queue statistics
final stats = await queueManager.getQueueStats();

print('Pending: ${stats.pendingCount}');
print('Failed: ${stats.failedCount}');
print('Retrying: ${stats.retryingCount}');
print('Oldest item age: ${stats.oldestItemAge.inMinutes} minutes');
print('Category breakdown: ${stats.categoryBreakdown}');
print('Priority breakdown: ${stats.priorityBreakdown}');

// Use with providers
final statsProvider = FutureProvider<QueueStats>((ref) async {
  final manager = ref.watch(queueManagerProvider);
  return await manager.getQueueStats();
});

Sync Observer System

class MySyncObserver implements SyncObserver {
  @override
  void onSyncStarted() {
    print('Sync started at ${DateTime.now()}');
  }

  @override
  void onSyncCompleted() {
    print('Sync completed successfully');
  }

  @override
  void onSyncFailed(Object error) {
    print('Sync failed: $error');
    // Send to analytics
    Analytics.track('sync_failed', {'error': error.toString()});
  }

  @override
  void onProgressChanged(int current, int total) {
    print('Progress: $current/$total');
    // Update UI progress bar
  }

  @override
  void onItemProcessed(String itemId, bool success) {
    print('Item $itemId processed: ${success ? "success" : "failed"}');
  }
}

// Register observer
final observer = MySyncObserver();
OfflineSyncLayer.instance.addObserver(observer);

// Don't forget to remove when done
OfflineSyncLayer.instance.removeObserver(observer);

// Analytics observer example
class AnalyticsSyncObserver implements SyncObserver {
  @override
  void onSyncStarted() {
    Analytics.trackEvent('sync_started');
  }

  @override
  void onSyncCompleted() {
    Analytics.trackEvent('sync_completed');
  }

  @override
  void onSyncFailed(Object error) {
    Analytics.trackEvent('sync_failed', properties: {
      'error': error.toString(),
    });
  }

  @override
  void onProgressChanged(int current, int total) {
    final percentage = (current / total * 100).toStringAsFixed(1);
    Analytics.trackEvent('sync_progress', properties: {
      'percentage': percentage,
      'current': current,
      'total': total,
    });
  }
}

OfflineSyncScope Widget

void main() {
  runApp(
    ProviderScope(
      child: OfflineSyncScope(
        config: SyncConfig.defaultConfig(),
        loadingWidget: Scaffold(
          body: Center(
            child: Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                CircularProgressIndicator(),
                SizedBox(height: 16),
                Text('Initializing offline sync...'),
              ],
            ),
          ),
        ),
        onInitialized: () {
          print('Offline sync ready!');
          // Register handlers after initialization
          _registerHandlers();
        },
        child: MyApp(),
      ),
    ),
  );
}

Complete Service Class Example

class OfflineSyncService {
  static Future<void> initialize() async {
    await Firebase.initializeApp();
    await FirebaseFirestore.instance.settings =
        const Settings(persistenceEnabled: true);

    await OfflineSyncLayer.instance.initialize(
      config: SyncConfig.defaultConfig(),
    );

    _registerHandlers();
  }

  static void _registerHandlers() {
    final sync = OfflineSyncLayer.instance;

    sync.registerOperationHandler('firestore_set', (data) async {
      await FirebaseFirestore.instance
          .collection(data['collection'])
          .doc(data['docId'])
          .set(data['payload']);
    });

    sync.registerOperationHandler('firestore_update', (data) async {
      await FirebaseFirestore.instance
          .collection(data['collection'])
          .doc(data['docId'])
          .update(data['payload']);
    });

    sync.registerOperationHandler('firestore_delete', (data) async {
      await FirebaseFirestore.instance
          .collection(data['collection'])
          .doc(data['docId'])
          .delete();
    });
  }

  static Future<void> create(String collection, String id, Map<String, dynamic> data) async {
    await OfflineSyncLayer.instance.submitOperation(
      category: 'firestore_set',
      priority: QueuePriority.high.value,
      idempotencyKey: IdempotencyKey.generate(),
      data: {'collection': collection, 'docId': id, 'payload': data},
    );
  }

  static Future<void> update(String collection, String id, Map<String, dynamic> updates) async {
    await OfflineSyncLayer.instance.submitOperation(
      category: 'firestore_update',
      priority: QueuePriority.normal.value,
      idempotencyKey: IdempotencyKey.generate(),
      data: {'collection': collection, 'docId': id, 'payload': updates},
    );
  }

  static Future<void> delete(String collection, String id) async {
    await OfflineSyncLayer.instance.submitOperation(
      category: 'firestore_delete',
      priority: QueuePriority.high.value,
      idempotencyKey: IdempotencyKey.generate(),
      data: {'collection': collection, 'docId': id},
    );
  }

  static Future<void> forceSync() async => OfflineSyncLayer.instance.sync();

  static Future<int> getPendingCount() async {
    final pending = await OfflineSyncLayer.instance.getPendingOperations();
    return pending.length;
  }

  static Future<QueueStats> getQueueStats() async {
    return await OfflineSyncLayer.instance.queueManager.getQueueStats();
  }

  static Future<void> clearQueue() async => OfflineSyncLayer.instance.clearQueue();

  static Future<void> retryFailed(String id) async =>
      OfflineSyncLayer.instance.retryFailedOperation(id);
}

Complete Todo App Example

Todo Model

class Todo {
  final String id;
  final String title;
  final bool completed;
  final DateTime createdAt;
  final DateTime? updatedAt;

  Todo({
    required this.id,
    required this.title,
    this.completed = false,
    required this.createdAt,
    this.updatedAt,
  });

  Map<String, dynamic> toJson() => {
    'id': id,
    'title': title,
    'completed': completed,
    'createdAt': createdAt.toIso8601String(),
    'updatedAt': updatedAt?.toIso8601String(),
  };

  factory Todo.fromJson(Map<String, dynamic> json) => Todo(
    id: json['id'],
    title: json['title'],
    completed: json['completed'] ?? false,
    createdAt: DateTime.parse(json['createdAt']),
    updatedAt: json['updatedAt'] != null ? DateTime.parse(json['updatedAt']) : null,
  );

  factory Todo.fromFirestore(DocumentSnapshot doc) {
    final data = doc.data() as Map<String, dynamic>;
    return Todo(
      id: doc.id,
      title: data['title'],
      completed: data['completed'],
      createdAt: (data['createdAt'] as Timestamp).toDate(),
      updatedAt: data['updatedAt'] != null
          ? (data['updatedAt'] as Timestamp).toDate()
          : null,
    );
  }

  Todo copyWith({String? title, bool? completed}) => Todo(
    id: id,
    title: title ?? this.title,
    completed: completed ?? this.completed,
    createdAt: createdAt,
    updatedAt: DateTime.now(),
  );
}

Todo Service

class TodoService {
  static Future<void> addTodo(Todo todo) async {
    await OfflineSyncLayer.instance.submitOperation(
      category: 'firestore_set',
      priority: QueuePriority.high.value,
      idempotencyKey: 'todo_${todo.id}_${DateTime.now().millisecondsSinceEpoch}',
      data: {
        'collection': 'todos',
        'docId': todo.id,
        'payload': todo.toJson(),
      },
    );
  }

  static Future<void> updateTodo(Todo todo) async {
    await OfflineSyncLayer.instance.submitOperation(
      category: 'firestore_update',
      priority: QueuePriority.normal.value,
      idempotencyKey: IdempotencyKey.generate(),
      data: {
        'collection': 'todos',
        'docId': todo.id,
        'payload': {
          'completed': todo.completed,
          'updatedAt': DateTime.now().toIso8601String(),
        },
      },
    );
  }

  static Future<void> deleteTodo(String todoId) async {
    await OfflineSyncLayer.instance.submitOperation(
      category: 'firestore_delete',
      priority: QueuePriority.high.value,
      idempotencyKey: 'delete_todo_${todoId}_${DateTime.now().millisecondsSinceEpoch}',
      data: {
        'collection': 'todos',
        'docId': todoId,
      },
    );
  }

  static Stream<List<Todo>> streamTodos() {
    return FirebaseFirestore.instance
        .collection('todos')
        .orderBy('createdAt', descending: true)
        .snapshots()
        .map((snapshot) => snapshot.docs
            .map((doc) => Todo.fromFirestore(doc))
            .toList());
  }

  static Future<void> forceSync() async => OfflineSyncLayer.instance.sync();
}

Todo List Page

final todoListProvider = StreamProvider.autoDispose<List<Todo>>((ref) {
  return TodoService.streamTodos();
});

class TodoListPage extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final todosAsync = ref.watch(todoListProvider);
    final pendingCount = ref.watch(pendingItemsCountProvider).valueOrNull ?? 0;
    final isSyncing = ref.watch(isSyncingProvider);

    return Scaffold(
      appBar: AppBar(
        title: Text('Offline Todo'),
        actions: [
          if (pendingCount > 0 || isSyncing)
            Padding(
              padding: EdgeInsets.symmetric(horizontal: 8),
              child: Center(
                child: Row(
                  children: [
                    if (isSyncing)
                      SizedBox(
                        width: 20,
                        height: 20,
                        child: CircularProgressIndicator(strokeWidth: 2),
                      ),
                    if (pendingCount > 0)
                      Padding(
                        padding: EdgeInsets.only(left: 4),
                        child: Text('$pendingCount'),
                      ),
                  ],
                ),
              ),
            ),
          IconButton(
            icon: Icon(Icons.sync),
            onPressed: () async {
              await TodoService.forceSync();
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Syncing...')),
              );
            },
          ),
        ],
      ),
      body: Stack(
        children: [
          todosAsync.when(
            data: (todos) {
              if (todos.isEmpty) {
                return Center(
                  child: Column(
                    mainAxisAlignment: MainAxisAlignment.center,
                    children: [
                      Icon(Icons.check_circle_outline, size: 64, color: Colors.grey),
                      SizedBox(height: 16),
                      Text('No todos yet', style: TextStyle(color: Colors.grey)),
                      SizedBox(height: 8),
                      Text('Add your first todo!', style: TextStyle(fontSize: 12)),
                    ],
                  ),
                );
              }

              return ListView.builder(
                itemCount: todos.length,
                itemBuilder: (context, index) {
                  final todo = todos[index];
                  return CheckboxListTile(
                    title: Text(
                      todo.title,
                      style: TextStyle(
                        decoration: todo.completed ? TextDecoration.lineThrough : null,
                      ),
                    ),
                    value: todo.completed,
                    onChanged: (completed) async {
                      await TodoService.updateTodo(todo.copyWith(completed: completed));
                    },
                    secondary: IconButton(
                      icon: Icon(Icons.delete, color: Colors.red),
                      onPressed: () async => TodoService.deleteTodo(todo.id),
                    ),
                  );
                },
              );
            },
            loading: () => Center(child: CircularProgressIndicator()),
            error: (err, stack) => Center(
              child: Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  Icon(Icons.error_outline, size: 64, color: Colors.red),
                  SizedBox(height: 16),
                  Text('Error loading todos: $err'),
                  SizedBox(height: 8),
                  ElevatedButton(
                    onPressed: () => ref.invalidate(todoListProvider),
                    child: Text('Retry'),
                  ),
                ],
              ),
            ),
          ),
          if (isSyncing)
            Positioned(
              top: 0,
              left: 0,
              right: 0,
              child: LinearProgressIndicator(),
            ),
        ],
      ),
      floatingActionButton: FloatingActionButton(
        child: Icon(Icons.add),
        onPressed: () async {
          final newTodo = Todo(
            id: DateTime.now().millisecondsSinceEpoch.toString(),
            title: 'New Task ${DateTime.now().hour}:${DateTime.now().minute}',
            completed: false,
            createdAt: DateTime.now(),
          );
          await TodoService.addTodo(newTodo);
        },
      ),
    );
  }
}

🏗️ Architecture

UI Widgets
    ↓
Riverpod Providers (Real-time data)
    ↓
OfflineSyncLayer (Queue management)
    ↓
QueueManager (Orchestration)
    ↓
Retry / Conflict / Connectivity Systems
    ↓
Persistence Layer (Hive for queue + Firestore for data)
    ↓
Backend APIs / Firebase

📂 Package Structure

lib/
 ├── core/
 │   ├── sync_layer.dart
 │   ├── sync_config.dart
 │   ├── sync_metrics.dart
 │   ├── sync_progress.dart
 │   ├── sync_state_machine.dart
 │   ├── sync_observer.dart        (NEW in v1.0.0)
 │   └── offline_sync_scope.dart   (NEW in v1.0.0)
 ├── queue/
 │   ├── queue_manager.dart
 │   ├── queue_item.dart
 │   ├── queue_priority.dart
 │   ├── queue_category.dart
 │   ├── retry_strategy.dart
 │   ├── hive_registry.dart
 │   ├── queue_item_adapter.dart
 │   └── queue_stats.dart          (NEW in v1.0.0)
 ├── connectivity/
 ├── conflict/
 ├── firebase/
 │   ├── firestore_service.dart
 │   ├── storage_queue.dart
 │   └── auth_persistence.dart
 ├── providers/
 ├── ui/
 ├── mixins/
 ├── utils/
 └── riverpod_offline_sync.dart

Core Concepts

Queue Priorities

Priority Value Use Cases
critical 0 Payments, KYC
high 1 Orders, Messages
normal 2 Profile updates
low 3 Analytics
background 4 Cache refresh

Queue Categories

enum QueueCategory {
  uploads,
  orders,
  messages,
  payments,
  sync,
  analytics,
  media,
  documents,
  background,
}

Sync Strategies

Strategy Description
auto Automatic synchronization
manual Manual user-triggered sync
background Silent sync
pushOnly Push local changes only
pullOnly Pull remote changes only

Conflict Resolution

ConflictStrategy.serverWins
ConflictStrategy.clientWins
ConflictStrategy.merge
ConflictStrategy.lastWriteWins
ConflictStrategy.manualResolve

Example:

final resolver = ConflictResolver();

final resolved = await resolver.resolve(
  local: localData,
  remote: remoteData,
  strategy: ConflictStrategy.merge,
);

Features:

  • Deep merge support
  • Nested map resolution
  • List merging
  • Duplicate removal
  • Timestamp-based conflict handling
  • Ignored fields support (NEW in v1.0.0)

Providers

Sync Providers

final offlineSyncLayerProvider
final syncStateProvider
final syncProgressProvider
final syncMetricsProvider
final isSyncingProvider
final syncStatusTextProvider

Queue Providers

final queueManagerProvider
final pendingItemsProvider
final pendingItemsCountProvider
final queueBreakdownProvider

Connectivity Providers

final connectivityMonitorProvider
final connectivityStatusProvider
final isConnectedProvider

Methods

OfflineSyncLayer

// Initialize
await OfflineSyncLayer.instance.initialize();

// Submit operation
await OfflineSyncLayer.instance.submitOperation(
  category: 'orders',
  priority: 1,
  idempotencyKey: IdempotencyKey.generate(),
  data: {'key': 'value'},
);

// Manual sync
await OfflineSyncLayer.instance.sync();

// Clear queue
await OfflineSyncLayer.instance.clearQueue();

// Get pending operations
final pending = await OfflineSyncLayer.instance.getPendingOperations();

// Retry failed operation
await OfflineSyncLayer.instance.retryFailedOperation('item_id');

// Check initialization
if (OfflineSyncLayer.instance.isInitialized) {
  // Safe to use
}

// Observer management (NEW in v1.0.0)
OfflineSyncLayer.instance.addObserver(myObserver);
OfflineSyncLayer.instance.removeObserver(myObserver);

// Dispose
await OfflineSyncLayer.instance.dispose();

QueueManager

final manager = QueueManager();

await manager.initialize();

await manager.enqueue(
  category: 'orders',
  priority: 1,
  data: {},
);

await manager.processQueue(maxConcurrent: 3);

await manager.retryFailed('item_id');

// Get queue statistics (NEW in v1.0.0)
final stats = await manager.getQueueStats();
print('Failed items: ${stats.failedCount}');
print('Retrying items: ${stats.retryingCount}');

StorageQueue

final storageQueue = StorageQueue();

// Upload file with progress (NEW in v1.0.0)
await storageQueue.uploadFile(
  file: file,
  path: 'uploads/image.jpg',
  idempotencyKey: IdempotencyKey.generate(),
  onProgress: (percentage) {
    print('Progress: ${(percentage * 100).toStringAsFixed(1)}%');
  },
);

// Control upload
storageQueue.pauseUpload('key');
storageQueue.resumeUpload('key');
storageQueue.cancelUpload('key');

UI Components

ConnectivityBanner

ConnectivityBanner(
  child: HomePage(),
)

SyncStatusIndicator

SyncStatusIndicator(
  showAsFloatingAction: true,
)

SyncProgressBar

SyncProgressBar(
  showDetails: true,
)

OfflineToast

OfflineToast(
  child: HomePage(),
)

DebugPanel

showModalBottomSheet(
  context: context,
  isScrollControlled: true,
  backgroundColor: Colors.transparent,
  builder: (_) => const DebugPanel(),
);

Features: Queue inspection, sync metrics, connectivity status, retry operations, queue breakdown, manual sync controls.

Configuration

const config = SyncConfig(
  autoSyncOnReconnect: true,
  syncImmediately: true,
  autoSyncInterval: Duration(minutes: 15),
  maxRetries: 5,
  initialRetryDelay: Duration(seconds: 2),
  maxConcurrentOperations: 3,
  enableMetrics: true,
  enableDebugLogging: false,
  syncOnWiFiOnly: false,
  maxQueueSize: 1000,
  conflictStrategy: ConflictStrategy.merge, // NEW in v1.0.0
);

Predefined Configurations:

SyncConfig.defaultConfig()      // Balanced
SyncConfig.aggressive()         // Fast sync, more battery
SyncConfig.batteryFriendly()    // Less frequent sync
SyncConfig.wifiOnly()           // Only sync on WiFi

Metrics & Analytics

final metrics = OfflineSyncLayer.instance.metrics;

print('Success rate: ${metrics.successRatePercentage}%');
print('Total syncs: ${metrics.totalSyncs}');
print('Failed syncs: ${metrics.failedSyncs}');
print('Avg duration: ${metrics.averageSyncDuration}');

Retry System

final delay = BackoffCalculator.calculateNextRetry(attempt: 3);
// Returns: Duration(seconds: 8) for attempt 3 with base delay 2

Features: Exponential backoff, delayed retry scheduling, retry tracking, configurable retry count.

Connectivity Monitoring

final connected = OfflineSyncLayer.instance.connectivityMonitor.isConnected;
final isWifi = await OfflineSyncLayer.instance.connectivityMonitor.isWifiConnected;

// Listen to changes
OfflineSyncLayer.instance.connectivityMonitor.onConnectivityChanged.listen((status) {
  print('Connectivity: $status');
});

Utilities

Idempotency Keys

// Auto-generate
final key = IdempotencyKey.generate();

// Custom key
final customKey = 'user_${userId}_action_${timestamp}';

Logger

OfflineLogger.isEnabled = true;

OfflineLogger.info('Sync started');
OfflineLogger.error('Sync failed: $error');
OfflineLogger.debug('Queue processed: ${items.length} items');

Backoff Calculator

final delay = BackoffCalculator.calculateNextRetry(3);
// Exponential backoff: 2^3 = 8 seconds

Examples

Offline Orders

await OfflineSyncLayer.instance.submitOperation(
  category: QueueCategory.orders.label,
  priority: QueuePriority.high.value,
  idempotencyKey: IdempotencyKey.generate(),
  data: {
    'product': 'Laptop',
    'quantity': 1,
    'price': 999.99,
    'userId': currentUser.id,
  },
);

Chat Messages

await OfflineSyncLayer.instance.submitOperation(
  category: QueueCategory.messages.label,
  priority: QueuePriority.high.value,
  idempotencyKey: IdempotencyKey.generate(),
  data: {
    'message': 'Hello!',
    'recipientId': 'user456',
    'timestamp': DateTime.now().toIso8601String(),
  },
);

Analytics Tracking

await OfflineSyncLayer.instance.submitOperation(
  category: 'analytics',
  priority: QueuePriority.low.value,
  idempotencyKey: IdempotencyKey.generate(),
  data: {
    'event_name': 'button_click',
    'properties': {
      'button': 'add_todo',
      'screen': 'home',
    },
    'timestamp': DateTime.now().toIso8601String(),
  },
);

Debugging

Enable Debug Logging

OfflineLogger.isEnabled = true;

Show Debug Panel

showModalBottomSheet(
  context: context,
  isScrollControlled: true,
  backgroundColor: Colors.transparent,
  builder: (BuildContext context) => const DebugPanel(),
);

Manual Inspection

// Get pending operations
final operations = await OfflineSyncLayer.instance.getPendingOperations();
print('Pending: ${operations.length}');

// Get queue statistics (NEW in v1.0.0)
final stats = await OfflineSyncLayer.instance.queueManager.getQueueStats();
print('Failed: ${stats.failedCount}');
print('Retrying: ${stats.retryingCount}');

// Get metrics
final metrics = OfflineSyncLayer.instance.metrics;
print('Success rate: ${metrics.successRatePercentage}%');

// Check connectivity
final isConnected = OfflineSyncLayer.instance.connectivityMonitor.isConnected;
print('Connected: $isConnected');

// Check initialization
final isInitialized = OfflineSyncLayer.instance.isInitialized;
print('Initialized: $isInitialized');

Troubleshooting

❌ HiveError: A Hive box with name 'offline_queue' already exists

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Hive.initFlutter();
  await OfflineSyncLayer.instance.initialize();
  runApp(const ProviderScope(child: MyApp()));
}

❌ Hive has not been initialized

await Hive.initFlutter();
await OfflineSyncLayer.instance.initialize();

❌ No Firebase App '[DEFAULT]' has been created

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(); // Initialize first
  await OfflineSyncLayer.instance.initialize();
  runApp(const ProviderScope(child: MyApp()));
}

❌ Firestore persistence enabled too late

await Firebase.initializeApp();
await FirebaseFirestore.instance.settings =
    const Settings(persistenceEnabled: true); // Before sync layer
await OfflineSyncLayer.instance.initialize();

❌ Queue Stuck Processing

// 1. Force sync
await OfflineSyncLayer.instance.sync();

// 2. Verify handler is registered
OfflineSyncLayer.instance.registerOperationHandler('your_category', ...);

// 3. Check WiFi-only mode
if (syncConfig.syncOnWiFiOnly) {
  final isWifi = await OfflineSyncLayer.instance.connectivityMonitor.isWifiConnected;
  if (!isWifi) print('WiFi-only mode active');
}

// 4. Retry manually
await OfflineSyncLayer.instance.retryFailedOperation('item_id');

❌ Duplicate Operations

await OfflineSyncLayer.instance.submitOperation(
  category: 'orders',
  priority: 1,
  data: orderData,
  idempotencyKey: 'unique_order_${orderData['id']}', // Custom key
);

❌ OfflineSyncLayer not initialized

if (OfflineSyncLayer.instance.isInitialized) {
  await OfflineSyncLayer.instance.submitOperation(...);
} else {
  print('Sync layer not ready yet');
}

✅ Queue Statistics Not Updating (NEW in v1.0.0)

// Force refresh stats
final stats = await OfflineSyncLayer.instance.queueManager.getQueueStats();

// Or invalidate provider
ref.invalidate(pendingItemsCountProvider);

✅ Observer Not Receiving Events (NEW in v1.0.0)

// Ensure observer is added after initialization
await OfflineSyncLayer.instance.initialize();
OfflineSyncLayer.instance.addObserver(myObserver);

Debug Checklist

  • OfflineSyncLayer.instance.isInitialized is true
  • Handlers registered for all categories
  • Firebase initialized before sync layer
  • Firestore persistence enabled before sync layer
  • Connectivity monitor working
  • Queue has items
  • No console errors
  • Hive initialized
  • Unique idempotency keys used
  • WiFi-only mode not blocking (if enabled)

FAQ

Q: Does it work offline? A: Yes. Queue operations persist locally using Hive and sync automatically when online.

Q: What happens if the app restarts? A: Queue data persists using Hive and resumes automatically.

Q: Does it support Firebase? A: Yes. Full Firestore, Storage, and Auth integrations are included.

Q: Can I use custom backends? A: Yes. Works with REST APIs, GraphQL, or any backend.

Q: How are duplicates prevented? A: Idempotency keys prevent duplicate operations.

Q: Does it support large uploads? A: Yes. Includes pause, resume, cancel, and progress tracking.

Q: Is it Riverpod-only? A: Core sync system works independently, but Riverpod integration is included.

Q: Do I need Firestore persistence enabled? A: Recommended for a complete offline-first experience. It works alongside riverpod_offline_sync.

Q: How does this compare to Firebase's offline? A: Firebase handles query caching; riverpod_offline_sync handles operation queuing with retries, conflict resolution, and full control.

Q: Can I use both together? A: Yes! Use Firestore native offline for reads and riverpod_offline_sync for critical writes needing control.

Q: What's new in v1.0.0? A: Queue statistics API, sync observer system, OfflineSyncScope widget, improved queue trimming, UUID-based IDs, enhanced progress tracking, and better connectivity handling.

🎯 Handler Registration Checklist

Required handlers to register in main():

  • ✅ firestore_set — For create/set operations
  • ✅ firestore_update — For update operations
  • ✅ firestore_delete — For delete operations
  • ✅ firestore_batch — For batch writes (optional)
  • ✅ api_request — For custom API endpoints
  • ✅ analytics — For analytics tracking

No handler needed for:

  • ✅ Firebase Storage uploads (uses StorageQueue)
  • ✅ Firestore real-time listeners (native)

📊 Package Comparison

Feature Firebase Only With riverpod_offline_sync
Offline reads ✅ Yes (cached queries) ✅ Yes (via Firestore)
Offline writes ✅ Basic queue ✅ Full queue control
Pause/Resume operations ❌ No ✅ Yes
Conflict resolution ❌ Last write wins ✅ Multiple strategies
Retry logic ✅ Basic ✅ Customizable
Queue inspection ❌ No ✅ Debug panel + metrics
Queue Statistics ❌ No ✅ Yes (v1.0.0)
Sync Observers ❌ No ✅ Yes (v1.0.0)
Idempotency ❌ Manual ✅ Built-in
Progress tracking ❌ No ✅ Real-time streams
Upload control ❌ No ✅ Pause/Resume/Cancel

License

MIT License — see LICENSE file for details.

❤️ Built For Offline-First Flutter Apps

Reliable synchronization for super apps, delivery apps, chat apps, POS systems, CRM apps, warehouse systems, social apps, field-service apps, and media upload apps.

Perfect for Firebase offline-first development! 🚀

Libraries

riverpod_offline_sync