Poorgramer-Zack/dart-expert-skills / skills/flutter-expert
building-flutter-production-apps
VerifiedExpert-level guidance for Flutter production applications: architecture decisions (Clean/Layered/Hexagonal/Feature-First), advanced state management (BLoC/Riverpod/GetX), performance optimization (eliminating jank, memory profiling, reducing rebuild overhead), code review with design pattern enforcement, scalability assessments, native platform integration (MethodChannel/EventChannel/FFI), complex UI challenges (custom render objects, slivers), testing strategies (unit/widget/integration/golden), CI/CD pipeline architecture, build optimization, and accessibility compliance. Triggers: 'architecture decision', 'design pattern', 'performance issue', 'code review', 'production problem', 'scaling concerns', 'best practices', 'technical debt', 'refactoring strategy'. Essential for complex enterprise apps, critical production debugging, architectural refactors, or when choosing between competing technical approaches.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.3 KB |
| references/accessibility.md | markdown | 6.7 KB |
| references/animation.md | markdown | 9.9 KB |
| references/app-size.md | markdown | 5.1 KB |
| references/architecture-decision-matrix.md | markdown | 16.2 KB |
| references/architecture.md | markdown | 7.0 KB |
| references/caching.md | markdown | 8.4 KB |
| references/concurrency.md | markdown | 7.7 KB |
| references/error-handling.md | markdown | 3.9 KB |
| references/home-screen-widget.md | markdown | 8.8 KB |
| references/http-and-json.md | markdown | 8.0 KB |
| references/layout.md | markdown | 5.2 KB |
| references/localization.md | markdown | 6.1 KB |
| references/native-interop.md | markdown | 9.3 KB |
| references/performance.md | markdown | 7.3 KB |
| references/platform-views.md | markdown | 13.3 KB |
| references/plugins.md | markdown | 6.5 KB |
| references/system-ui.md | markdown | 3.3 KB |
| references/theming.md | markdown | 6.2 KB |
references/caching.md
View on GitHub---
name: "flutter-caching"
description: "Cache data in a Flutter app"
metadata:
last_modified: "2026-03-12 11:18:17 (GMT+8)"
---
# 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.
```dart
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`.
```dart
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.
```dart
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):**
```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):**
```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`.
```dart
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`).
```dart
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.
1. **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.
2. **Check `operator ==` overrides:** Ensure `operator ==` is NOT overridden on `Widget` objects unless they are leaf widgets whose properties rarely change.
3. **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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |