Building Offline-First Flutter Apps

April 5, 2026·5 min read

Most mobile apps assume a reliable internet connection. In the real world — spotty 3G, underground metros, rural areas, airplane mode — that assumption breaks constantly. Offline-first means your app works fully without connectivity and syncs seamlessly when it returns.

Here's how to build it.

The Core Pattern

Offline-first follows a simple rule: read from local storage, write to local storage, sync with server in the background.

User action → Write to local DB → Update UI → Queue sync job
                                              ↓
                                   Server ← Sync when online

The user sees instant responses because they're always reading from local data. The server eventually gets consistent.

Choose Your Local Database

Drift (formerly Moor) is my recommendation for Flutter — it's a type-safe SQLite wrapper with generated code, reactive queries, and migration support.

flutter pub add drift drift_flutter
flutter pub add --dev build_runner drift_dev

Define your schema:

class Tasks extends Table {
  IntColumn

May 1, 2026·4 min read

Flutter State Management: Riverpod vs Bloc vs Provider

April 20, 2026·4 min read

Flutter Performance Optimisation: A Practical Guide

import 'package:connectivity_plus/connectivity_plus.dart';
 
class ConnectivityService {
  final _connectivity = Connectivity();
 
  Stream<bool> get isOnline => _connectivity.onConnectivityChanged
      .map((result) => result != ConnectivityResult.none);
 
  Future<bool> get currentlyOnline async {
    final result = await _connectivity.checkConnectivity();
    return result != ConnectivityResult.none;
  }
}

class SyncEngine {
  final AppDatabase _db;
  final ApiClient _api;
 
  SyncEngine(this._db, this._api);
 
  Future<void> sync() async {
    final pending = await _db.getPendingTasks();
 
    for (final task in pending) {
      try {
        if (task.syncId == null) {
          // New item — create on server
          final serverTask = await _api.createTask(task);
          await _db.updateTask(
            task.copyWith(syncId: serverTask.id, needsSync: false),
          );
        } else {
          // Existing item — update on server
          await _api.updateTask(task.syncId!, task);
          await _db.markSynced(task.id);
        }
      } catch (e) {
        // Don't crash the sync — move on, retry next time
        log('Sync failed for task ${task.id}: $e');
      }
    }
  }
}

class SyncManager {
  StreamSubscription? _sub;
 
  void start(ConnectivityService connectivity, SyncEngine engine) {
    _sub = connectivity.isOnline.listen((online) {
      if (online) engine.sync();
    });
  }
 
  void dispose() => _sub?.cancel();
}

import 'package:uuid/uuid.dart';
 
class TaskRepository {
  Future<void> createTask(TaskCompanion task) async {
    final idempotencyKey = const Uuid().v4();
 
    // Store key locally so we can retry with the same key
    await _db.into(_db.tasks).insert(
      task.copyWith(idempotencyKey: Value(idempotencyKey)),
    );
 
    // Server uses this key to deduplicate
    await _api.createTask(task, idempotencyKey: idempotencyKey);
  }
}

class SyncIndicator extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final pendingCount = ref.watch(pendingSyncCountProvider);
 
    if (pendingCount == 0) return const SizedBox();
 
    return Row(
      children: [
        const Icon(Icons.cloud_upload_outlined, size: 14, color: Colors.amber),
        const SizedBox(width: 4),
        Text(
          '$pendingCount unsynced',
          style: const TextStyle(fontSize: 12, color: Colors.amber),
        ),
      ],
    );
  }
}

Building Offline-First Flutter Apps

The Core Pattern

Choose Your Local Database

Related Posts

Flutter State Management: Riverpod vs Bloc vs Provider

Flutter Performance Optimisation: A Practical Guide

Track Connectivity

The Sync Engine

Handling Conflicts

Idempotency Keys

Show Sync Status in the UI

The Offline-First Checklist