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. 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. Instantiate and pre-warm the engine in the Application class. Store it in the FlutterEngineCache . 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
(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).