flutter-caching

SKILL.md

flutter-caching-and-performance

Goal

Implements advanced caching, offline-first data persistence, and performance optimization strategies in Flutter applications. Evaluates application requirements to select and integrate the appropriate local caching mechanism (in-memory, persistent, file system, or on-device databases). Configures Android-specific FlutterEngine caching to minimize initialization latency. Optimizes widget rendering, image caching, and scrolling performance while adhering to current Flutter API standards and avoiding expensive rendering operations.

Instructions
1. Evaluate and Select Caching Strategy (Decision Logic)

Analyze the user's data retention requirements using the following decision tree to select the appropriate caching mechanism:

Is the data temporary and only needed for the current session?

Yes: Use In-memory caching.

Is the data small, simple key-value pairs (e.g., user preferences)?

Yes: Use shared_preferences.

Is the data large, relational, or requires complex querying?

Yes: Use On-device databases (e.g., sqflite). Proceed to Step 3.

Is the data large binary files, custom documents, or JSON blobs?

Yes: Use File system caching (path_provider). Proceed to Step 2.

Is the data network images?

Yes: Use Image caching (cached_network_image or custom ImageCache). Proceed to Step 6.

Is the goal to reduce Android Flutter UI warm-up time?

Yes: Use FlutterEngine caching. Proceed to Step 5.

STOP AND ASK THE USER: "Based on your requirements, which data type and size are we handling? Should I implement SQLite, File System caching, or a different strategy?"

2. Implement File System Caching

When shared_preferences is insufficient for larger data, use path_provider and dart:io to persist data to the device's hard drive.

import 'dart:io';
import 'package:path_provider/path_provider.dart';

class FileCacheService {
  Future<String> get _localPath async {
    // Use getTemporaryDirectory() for system-cleared cache
    // Use getApplicationDocumentsDirectory() for persistent data
    final directory = await getApplicationDocumentsDirectory();
    return directory.path;
  }

  Future<File> get _localFile async {
    final path = await _localPath;
    return File('$path/cached_data.json');
  }

  Future<File> writeData(String data) async {
    final file = await _localFile;
    return file.writeAsString(data);
  }

  Future<String?> readData() async {
    try {
      final file = await _localFile;
      return await file.readAsString();
    } catch (e) {
      return null; // Cache miss
    }
  }
}

3. Implement SQLite Persistence

For large datasets requiring improved performance over simple files, implement an on-device database using sqflite.

import 'package:path/path.dart';
import 'package:sqflite/sqflite.dart';

class DatabaseService {
  late Database _database;

  Future<void> initDB() async {
    _database = await openDatabase(
      join(await getDatabasesPath(), 'app_cache.db'),
      onCreate: (db, version) {
        return db.execute(
          'CREATE TABLE cache_data(id INTEGER PRIMARY KEY, key TEXT, payload TEXT)',
        );
      },
      version: 1,
    );
  }

  Future<void> insertCache(String key, String payload) async {
    await _database.insert(
      'cache_data',
      {'key': key, 'payload': payload},
      conflictAlgorithm: ConflictAlgorithm.replace,
    );
  }

  Future<String?> getCache(String key) async {
    final List<Map<String, Object?>> maps = await _database.query(
      'cache_data',
      where: 'key = ?',
      whereArgs: [key], // MUST use whereArgs to prevent SQL injection
    );
    if (maps.isNotEmpty) {
      return maps.first['payload'] as String;
    }
    return null;
  }
}

4. Implement Offline-First Repository (Stream-based)

Combine local caching and remote fetching. Yield the cached data first (cache hit), then fetch from the network, update the cache, and yield the fresh data.

Stream<UserProfile> getUserProfile() async* {
  // 1. Check local cache
  final localData = await _databaseService.getCache('user_profile');
  if (localData != null) {
    yield UserProfile.fromJson(localData);
  }

  // 2. Fetch remote data
  try {
    final remoteData = await _apiClient.fetchUserProfile();
    // 3. Update cache
    await _databaseService.insertCache('user_profile', remoteData.toJson());
    // 4. Yield fresh data
    yield remoteData;
  } catch (e) {
    // Handle network failure; local data has already been yielded
  }
}

5. Implement FlutterEngine Caching (Android)

To minimize Flutter's initialization time when adding Flutter screens to an Android app, pre-warm and cache the FlutterEngine.

Pre-warm in Application class (Kotlin):

class MyApplication : Application() {
  lateinit var flutterEngine : FlutterEngine
  override fun onCreate() {
    super.onCreate()
    flutterEngine = FlutterEngine(this)
    // Optional: Configure initial route before executing entrypoint
    flutterEngine.navigationChannel.setInitialRoute("/cached_route");
    flutterEngine.dartExecutor.executeDartEntrypoint(
      DartExecutor.DartEntrypoint.createDefault()
    )
    FlutterEngineCache.getInstance().put("my_engine_id", flutterEngine)
  }
}

Consume in Activity/Fragment (Kotlin):

// For Activity
startActivity(
  FlutterActivity
    .withCachedEngine("my_engine_id")
    .backgroundMode(FlutterActivityLaunchConfigs.BackgroundMode.transparent)
    .build(this)
)

// For Fragment
val flutterFragment = FlutterFragment.withCachedEngine("my_engine_id")
    .renderMode(FlutterView.RenderMode.texture)
    .shouldAttachEngineToActivity(false)
    .build()

6. Optimize Image and Scroll Caching

Apply strict constraints to image caching and scrolling to prevent GPU memory bloat and layout passes.

ImageCache Validation:
Verify cache hits without triggering loads using containsKey.

class CustomImageCache extends ImageCache {
  @override
  bool containsKey(Object key) {
    // Check if cache is tracking this key
    return super.containsKey(key); 
  }
}

ScrollCacheExtent Implementation:
Use the strongly-typed ScrollCacheExtent object for scrolling widgets (replaces deprecated cacheExtent and cacheExtentStyle).

ListView(
  // Use ScrollCacheExtent.pixels for pixel-based caching
  scrollCacheExtent: const ScrollCacheExtent.pixels(500.0),
  children: [ ... ],
)

Viewport(
  // Use ScrollCacheExtent.viewport for fraction-based caching
  scrollCacheExtent: const ScrollCacheExtent.viewport(0.5),
  slivers: [ ... ],
)

7. Validate-and-Fix Performance

Review the generated UI code for performance pitfalls.

Check for saveLayer() triggers: Ensure Opacity, ShaderMask, ColorFilter, and Clip.antiAliasWithSaveLayer are only used when absolutely necessary. Replace Opacity with semitransparent colors or FadeInImage where possible.

Check operator == overrides: Ensure operator == is NOT overridden on Widget objects unless they are leaf widgets whose properties rarely change.

Check Intrinsic Passes: Ensure ListView and GridView use lazy builder methods (ListView.builder) and avoid intrinsic layout passes by setting fixed sizes where possible.

Constraints

SQL Injection Prevention: ALWAYS use whereArgs in sqflite queries. NEVER use string interpolation for SQL where clauses.

Engine Lifecycle: When using a cached FlutterEngine in Android, remember it outlives the Activity/Fragment. Explicitly call FlutterEngine.destroy() when it is no longer needed to clear resources.

Image Caching Limits: Raster cache entries are expensive to construct and use significant GPU memory. Only cache images when absolutely necessary. Do not artificially inflate ImageCache.maxByteSize.

Widget Equality: Do not override operator == on widgets to force caching, as this degrades performance to O(N²). Rely on const constructors instead.

Scroll Extents: NEVER use the deprecated cacheExtent (double) or cacheExtentStyle. ALWAYS use the ScrollCacheExtent object.

Web Workers: If targeting Flutter Web, remember that Dart isolates are not supported. Do not generate isolate-based background parsing for web targets.

2