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

Apply the appropriate caching mechanism based on the data lifecycle and size requirements.

• 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

Design repositories as the single source of truth, combining local databases and remote API clients.

#### Read Operations (Stream Approach) Yield local data immediately for fast UI rendering, then fetch remote data, update the local cache, and yield the fresh data.

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 Determine the write strategy based on data criticality:

• 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 Add a synchronized boolean flag to your data models. Keep the model immutable (Freezed): never mutate the flag in place. Produce a new instance with copyWith(synchronized: true) and write that back. Run a periodic background task (e.g., via workmanager or a Timer) to push unsynchronized local changes to the server.

Managing File System and SQLite Persistence

#### File System Caching Use path_provider to locate the correct directory.

• 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 Use sqflite for relational data caching. Always use whereArgs to prevent SQL injection.

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 Image I/O and decompression are expensive.

• 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 When configuring caching for scrollable widgets (ListView, GridView, Viewport), use the scrollCacheExtent property with a ScrollCacheExtent object. Do not use the deprecated cacheExtent and cacheExtentStyle properties.

// 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)

To eliminate the non-trivial warm-up time of a FlutterEngine when adding Flutter to an existing Android app, pre-warm and cache the engine.

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)
)

Note: You cannot set an initial route via the Activity/Fragment builder when using a cached engine. Set the initial route on the engine's navigation channel before executing the Dart entrypoint.

Workflows

#### Workflow: Implementing an Offline-First Repository Follow these steps to implement a robust offline-first data layer.

• [ ] 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 Follow these steps to cache the FlutterEngine for seamless Android integration.

• [ ] 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).