Implementing Flutter Caching and Offline-First Architectures

Contents

• Selecting a Caching Strategy
• Implementing Offline-First Data Synchronization
• Managing File System and SQLite Persistence
• Optimizing UI, Scroll, and Image Caching
• Caching the FlutterEngine (Android)
• Workflows

Selecting a Caching Strategy

• If storing small, non-critical UI states or preferences: Use

  shared_preferences

  .
• If storing large, structured datasets: Use on-device databases (SQLite via

  sqflite

  , Drift, Hive CE, or Isar).
• If storing binary data or large media: Use file system caching via

  path_provider

  .
• If retaining user session state (navigation, scroll positions): Implement Flutter's built-in state restoration to sync the Element tree with the engine.
• If optimizing Android initialization: Pre-warm and cache the

  FlutterEngine

  .

Implementing Offline-First Data Synchronization

Read Operations (Stream Approach)

Stream<UserProfile> getUserProfile() async* {
  // 1. Yield local cache first
  final localProfile = await _databaseService.fetchUserProfile();
  if (localProfile != null) yield localProfile;

  // 2. Fetch remote, update cache, yield fresh data
  try {
    final remoteProfile = await _apiClientService.getUserProfile();
    await _databaseService.updateUserProfile(remoteProfile);
    yield remoteProfile;
  } catch (e) {
    // Handle network failure; UI already has local data
  }
}

Write Operations

• If strict server synchronization is required (Online-only): Attempt the API call first. Only update the local database if the API call succeeds.
• If offline availability is prioritized (Offline-first): Write to the local database immediately. Attempt the API call. If the API call fails, flag the local record for background synchronization.

Background Synchronization

synchronized

workmanager

Timer

Managing File System and SQLite Persistence

File System Caching

path_provider

• Use

  getApplicationDocumentsDirectory()

  for persistent data.
• Use

  getTemporaryDirectory()

  for cache data the OS can clear.

Future<File> get _localFile async {
  final directory = await getApplicationDocumentsDirectory();
  return File('${directory.path}/cache.txt');
}

SQLite Persistence

sqflite

whereArgs

Future<void> updateCachedRecord(Record record) async {
  final db = await database;
  await db.update(
    'records',
    record.toMap(),
    where: 'id = ?',
    whereArgs: [record.id], // NEVER use string interpolation here
  );
}

Optimizing UI, Scroll, and Image Caching

Image Caching

• Use the

  cached_network_image

  package to handle file-system caching of remote images.
• Custom ImageProviders: If implementing a custom

  ImageProvider

  , override

  createStream()

  and

  resolveStreamForKey()

  instead of the deprecated

  resolve()

  method.
• Cache Sizing: The

  ImageCache.maxByteSize

  no longer automatically expands for large images. If loading images larger than the default cache size, manually increase

  ImageCache.maxByteSize

  or subclass

  ImageCache

  to implement custom eviction logic.

Scroll Caching

ListView

GridView

Viewport

scrollCacheExtent

ScrollCacheExtent

cacheExtent

cacheExtentStyle

// Correct implementation
ListView(
  scrollCacheExtent: const ScrollCacheExtent.pixels(500.0),
  children: // ...
)

Viewport(
  scrollCacheExtent: const ScrollCacheExtent.viewport(0.5),
  slivers: // ...
)

Widget Caching

• Avoid overriding

  operator ==

  on

  Widget

  objects. It causes O(N²) behavior during rebuilds.
• Exception: You may override

  operator ==

  only on leaf widgets (no children) where comparing properties is significantly faster than rebuilding, and the properties rarely change.
• Prefer using

  const

  constructors to allow the framework to short-circuit rebuilds automatically.

Caching the FlutterEngine (Android)

FlutterEngine

1. Instantiate and pre-warm the engine in the

   Application

   class.
2. Store it in the

   FlutterEngineCache

   .
3. Retrieve it using

   withCachedEngine

   in the

   FlutterActivity

   or

   FlutterFragment

   .

// 1. Pre-warm in Application class
val flutterEngine = FlutterEngine(this)
flutterEngine.navigationChannel.setInitialRoute("/cached_route")
flutterEngine.dartExecutor.executeDartEntrypoint(DartEntrypoint.createDefault())

// 2. Cache the engine
FlutterEngineCache.getInstance().put("my_engine_id", flutterEngine)

// 3. Use in Activity/Fragment
startActivity(
  FlutterActivity.withCachedEngine("my_engine_id").build(this)
)

Workflows

Workflow: Implementing an Offline-First Repository

• Task Progress:
  • Define the data model with a

    synchronized

    boolean flag (default

    false

    ).
  • Implement the local

    DatabaseService

    (SQLite/Hive) with CRUD operations.
  • Implement the remote

    ApiClientService

    for network requests.
  • Create the

    Repository

    class combining both services.
  • Implement the read method returning a

    Stream<T>

    (yield local, fetch remote, update local, yield remote).
  • Implement the write method (write local, attempt remote, update

    synchronized

    flag).
  • Implement a background sync function to process records where

    synchronized == false

    .
  • Run validator -> review errors -> fix (Test offline behavior by disabling network).

Workflow: Pre-warming the Android FlutterEngine

• Task Progress:
  • Locate the Android

    Application

    class (create one if it doesn't exist and register in

    AndroidManifest.xml

    ).
  • Instantiate a new

    FlutterEngine

    .
  • (Optional) Set the initial route via

    navigationChannel.setInitialRoute()

    .
  • Execute the Dart entrypoint via

    dartExecutor.executeDartEntrypoint()

    .
  • Store the engine in

    FlutterEngineCache.getInstance().put()

    .
  • Update the target

    FlutterActivity

    or

    FlutterFragment

    to use

    .withCachedEngine("id")

    .
  • Run validator -> review errors -> fix (Verify no blank screen appears during transition).