Caching

What Is Caching?

Caching is the process of storing copies of data in a local storage layer so that future requests for that data can be served faster and with less network usage . It's essential for:

Performance – Faster data access (reading from disk or memory is faster than network)
Bandwidth – Reduces data usage and API calls
Offline support – Users can access data without an internet connection
User experience – No loading spinners for cached content

🎯 The Caching Hierarchy

Memory Cache – Fastest, but cleared when app restarts
Disk Cache – Slower than memory, but persists across app restarts
Network – Slowest, but always fresh

Caching Strategies

There are three main caching strategies used in Flutter apps:

📦

Memory Cache

Store data in RAM for fast access

💾

Disk Cache

Persist data to storage (SharedPreferences, Hive, SQLite)

🔄

Network Cache

Use HTTP caching headers (ETag, Cache-Control)

Simple Memory Cache

A memory cache stores data in a Map or Cache object. It's fast but cleared when the app restarts.

        lib/cache/memory_cache.dart – Simple Memory Cache
       
class MemoryCache<K, V> {
  final Map<K, V> _cache = {};

  final int maxSize;

  MemoryCache({this.maxSize = 100});

  void put(K key, V value) {
    if (_cache.length >= maxSize) {
      // Simple LRU: remove the first entry

      final firstKey = _cache.keys.first;
      _cache.remove(firstKey);
    }
    _cache[key] = value;
  }

  V? get(K key) {
    return _cache[key];
  }

  bool containsKey(K key) {
    return _cache.containsKey(key);
  }

  void remove(K key) {
    _cache.remove(key);
  }

  void clear() {
    _cache.clear();
  }

  int get size => _cache.length;
}

        lib/cache/album_cache.dart – Using the Cache
       
import 'memory_cache.dart';

class AlbumCache {
  final MemoryCache<String, Map<String, dynamic>> _cache = MemoryCache();

  // Cache key with a timeout

  static const Duration cacheDuration = Duration(minutes: 5);

  void put(String id, Map<String, dynamic> album) {
    _cache.put(id, album);
  }

  Map<String, dynamic>? get(String id) {
    return _cache.get(id);
  }

  bool has(String id) {
    return _cache.containsKey(id);
  }

  void clear() {
    _cache.clear();
  }
}

cache_manager Package

The cache_manager package provides a comprehensive caching solution with disk persistence and HTTP caching support.

📦 cache_manager Features

Disk caching – Persist data to local storage
HTTP caching – Respects Cache-Control headers
Customizable – Configure cache duration and size
Stream support – Works with images and files
Offline-first – Serve cached data when offline

pubspec.yaml – Add dependency


        dependencies:
    flutter_cache_manager: ^3.4.0

        lib/cache/cache_service.dart – Cache Manager Setup
       
import 'package:flutter_cache_manager/flutter_cache_manager.dart';

class CustomCacheManager extends BaseCacheManager {
  static const String key = 'customCache';

  static CustomCacheManager? _instance;

  CustomCacheManager._()
    : super(
        key,
        maxAgeCacheObject: Duration(days: 7),
        maxNrOfCacheObjects: 100,
        repo: CacheObjectRepository(),
      );

  static CustomCacheManager get instance {
    _instance ??= CustomCacheManager._();

    return _instance!;
  }
}

        lib/services/api_service.dart – Using Cache Manager
       
import 'dart:convert';

import 'package:http/http.dart' as http;

import '../cache/cache_service.dart';

class ApiService {
  final http.Client client;

  final CustomCacheManager cacheManager;

  ApiService({http.Client? client, CustomCacheManager? cacheManager})
    : client = client ?? http.Client(),
      cacheManager = cacheManager ?? CustomCacheManager.instance;

  // Method 1: Using cache for GET requests

  Future<Map<String, dynamic>> fetchDataWithCache(String url) async {
    // Check cache first

    final cachedFile = await cacheManager.getFileFromCache(url);

    if (cachedFile != null) {
      final content = await cachedFile.file.readAsString();

      return jsonDecode(content) as Map<String, dynamic>;
    }

    // Fetch from network if not cached

    final response = await client.get(
      Uri.parse(url),
      headers: {'Accept': 'application/json'},
    );

    if (response.statusCode == 200) {
      // Save to cache

      await cacheManager.putFile(url, response.bodyBytes, key: url);

      return jsonDecode(response.body) as Map<String, dynamic>;
    } else {
      throw Exception('Failed to fetch data: ${response.statusCode}');
    }
  }

  // Method 2: Get data (with offline support)

  Future<Map<String, dynamic>> fetchDataWithOfflineSupport(String url) async {
    try {
      // Try network first

      final response = await client.get(
        Uri.parse(url),
        headers: {'Accept': 'application/json'},
      );

      if (response.statusCode == 200) {
        // Update cache with fresh data

        await cacheManager.putFile(url, response.bodyBytes, key: url);

        return jsonDecode(response.body) as Map<String, dynamic>;
      } else {
        // If network fails, try cache

        final cachedFile = await cacheManager.getFileFromCache(url);

        if (cachedFile != null) {
          final content = await cachedFile.file.readAsString();

          return jsonDecode(content) as Map<String, dynamic>;
        }

        throw Exception('No data available offline');
      }
    } catch (e) {
      // If network fails, fall back to cache

      final cachedFile = await cacheManager.getFileFromCache(url);

      if (cachedFile != null) {
        final content = await cachedFile.file.readAsString();

        return jsonDecode(content) as Map<String, dynamic>;
      }

      throw Exception('Network error and no cached data available');
    }
  }

  // Clear cache

  Future<void> clearCache() async {
    await cacheManager.emptyCache();
  }
}

Offline-First Strategy

An offline-first strategy ensures your app works even without an internet connection by serving cached data when the network is unavailable.

        lib/services/offline_service.dart – Offline-First Service
       
import 'dart:convert';

import 'package:connectivity_plus/connectivity_plus.dart';

import 'package:http/http.dart' as http;

import 'package:shared_preferences/shared_preferences.dart';

class OfflineService {
  final http.Client client;

  final String cacheKeyPrefix = 'cached_data_';

  OfflineService({http.Client? client}) : client = client ?? http.Client();

  Future<Map<String, dynamic>> fetchData(String url) async {
    final connectivityResult = await Connectivity().checkConnectivity();

    // If we have internet, fetch fresh data

    if (connectivityResult != ConnectivityResult.none) {
      return _fetchFromNetwork(url);
    } else {
      // If no internet, try to load from cache

      return _loadFromCache(url);
    }
  }

  Future<Map<String, dynamic>> _fetchFromNetwork(String url) async {
    final response = await client.get(
      Uri.parse(url),
      headers: {'Accept': 'application/json'},
    );

    if (response.statusCode == 200) {
      final data = jsonDecode(response.body) as Map<String, dynamic>;

      // Save to cache for offline use

      await _saveToCache(url, data);

      return data;
    } else {
      // If network returns error, fall back to cache

      return _loadFromCache(url);
    }
  }

  Future<Map<String, dynamic>> _loadFromCache(String url) async {
    final prefs = await SharedPreferences.getInstance();

    final cacheKey = '$cacheKeyPrefix$url';

    final cachedData = prefs.getString(cacheKey);

    if (cachedData != null) {
      return jsonDecode(cachedData) as Map<String, dynamic>;
    } else {
      throw Exception('No cached data available');
    }
  }

  Future<void> _saveToCache(String url, Map<String, dynamic> data) async {
    final prefs = await SharedPreferences.getInstance();

    final cacheKey = '$cacheKeyPrefix$url';

    await prefs.setString(cacheKey, jsonEncode(data));
  }

  // Clear all cached data

  Future<void> clearCache() async {
    final prefs = await SharedPreferences.getInstance();

    final keys = prefs.getKeys().where((key) => key.startsWith(cacheKeyPrefix));

    for (var key in keys) {
      await prefs.remove(key);
    }
  }
}

pubspec.yaml – Add connectivity package


        dependencies:
    connectivity_plus: ^5.0.0
    shared_preferences: ^2.2.0

Complete Example: Cached Posts App

Here's a complete app that uses caching to display posts with offline support.

        lib/main.dart – Complete Cached App
       
import 'package:flutter/material.dart';

import 'package:http/http.dart' as http;

import 'package:shared_preferences/shared_preferences.dart';

import 'dart:convert';

class CachedPostService {
  final http.Client client;

  final String cacheKey = 'cached_posts';

  static const Duration cacheDuration = Duration(minutes: 10);

  CachedPostService({http.Client? client}) : client = client ?? http.Client();

  Future<List<dynamic>> getPosts() async {
    final prefs = await SharedPreferences.getInstance();

    // Check cache first

    final cachedData = prefs.getString(cacheKey);

    final cacheTime = prefs.getInt('${cacheKey}_time');

    // If cache exists and is not expired, return it

    if (cachedData != null && cacheTime != null) {
      final elapsed = DateTime.now().millisecondsSinceEpoch - cacheTime;

      if (elapsed < cacheDuration.inMilliseconds) {
        return jsonDecode(cachedData) as List<dynamic>;
      }
    }

    // Cache expired or doesn't exist, fetch from network

    final response = await client.get(
      Uri.parse('https://jsonplaceholder.typicode.com/posts'),
      headers: {'Accept': 'application/json'},
    );

    if (response.statusCode == 200) {
      final data = jsonDecode(response.body) as List<dynamic>;

      // Save to cache

      await prefs.setString(cacheKey, jsonEncode(data));

      await prefs.setInt(
        '${cacheKey}_time',
        DateTime.now().millisecondsSinceEpoch,
      );

      return data;
    } else {
      // If network fails, try to return stale cache

      if (cachedData != null) {
        return jsonDecode(cachedData) as List<dynamic>;
      }

      throw Exception('Failed to load posts and no cache available');
    }
  }

  Future<void> clearCache() async {
    final prefs = await SharedPreferences.getInstance();

    await prefs.remove(cacheKey);

    await prefs.remove('${cacheKey}_time');
  }

  Future<void> refreshCache() async {
    // Force refresh by clearing cache and fetching

    await clearCache();

    await getPosts();
  }
}

class PostsScreen extends StatefulWidget {
  @override
  State<PostsScreen> createState() => _PostsScreenState();
}

class _PostsScreenState extends State<PostsScreen> {
  final CachedPostService _service = CachedPostService();
  List<dynamic> _posts = [];

  bool _isLoading = true;

  bool _hasError = false;
  String? _errorMessage;

  bool _isFromCache = false;

  @override
  void initState() {
    super.initState();
    _loadPosts();
  }

  Future<void> _loadPosts() async {
    setState(() {
      _isLoading = true;
      _hasError = false;
      _errorMessage = null;
    });

    try {
      final posts = await _service.getPosts();
      setState(() {
        _posts = posts;
        _isLoading = false;

        // In a real app, you'd detect if data came from cache

        _isFromCache = true;
      });
    } catch (e) {
      setState(() {
        _isLoading = false;
        _hasError = true;
        _errorMessage = e.toString();
      });
    }
  }

  Future<void> _refresh() async {
    await _service.refreshCache();

    await _loadPosts();
  }

  Future<void> _clearCache() async {
    await _service.clearCache();

    await _loadPosts();
    ScaffoldMessenger.of(
      context,
    ).showSnackBar(SnackBar(content: Text('Cache cleared')));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('📦 Cached Posts'),
        centerTitle: true,
        actions: [
          IconButton(
            icon: Icon(Icons.refresh),
            onPressed: _refresh,
            tooltip: 'Refresh',
          ),
          IconButton(
            icon: Icon(Icons.delete_sweep),
            onPressed: _clearCache,
            tooltip: 'Clear Cache',
          ),
        ],
      ),
      body: _buildContent(),
    );
  }

  Widget _buildContent() {
    if (_isLoading) {
      return Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            CircularProgressIndicator(),
            SizedBox(height: 16),
            Text('Loading posts...'),
            Text(
              'Checking cache...',
              style: TextStyle(color: Colors.grey.shade400),
            ),
          ],
        ),
      );
    }

    if (_hasError) {
      return Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Icon(Icons.error, size: 64, color: Colors.red),
            SizedBox(height: 16),
            Text(
              'Unable to load posts',
              style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
            ),
            SizedBox(height: 8),
            Text(
              _errorMessage ?? 'An error occurred',
              textAlign: TextAlign.center,
              style: TextStyle(color: Colors.grey.shade600),
            ),
            SizedBox(height: 16),
            ElevatedButton(onPressed: _loadPosts, child: Text('Retry')),
          ],
        ),
      );
    }

    return Column(
      children: [
        // Cache status indicator
        Container(
          padding: EdgeInsets.symmetric(vertical: 8),
          color: _isFromCache ? Colors.green.shade50 : Colors.transparent,
          child: Row(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Icon(
                _isFromCache ? Icons.check_circle : Icons.cloud,
                size: 16,
                color: _isFromCache ? Colors.green : Colors.blue,
              ),
              SizedBox(width: 4),
              Text(
                _isFromCache
                    ? '${_posts.length} posts (cached)'
                    : '${_posts.length} posts',
                style: TextStyle(
                  fontSize: 12,
                  color: _isFromCache
                      ? Colors.green.shade700
                      : Colors.grey.shade600,
                ),
              ),
            ],
          ),
        ),
        Expanded(
          child: ListView.builder(
            itemCount: _posts.length,
            itemBuilder: (context, index) {
              final post = _posts[index];

              return Card(
                margin: EdgeInsets.symmetric(horizontal: 16, vertical: 4),
                child: ListTile(
                  leading: CircleAvatar(child: Text((index + 1).toString())),
                  title: Text(
                    post['title'] ?? 'No title',
                    style: TextStyle(fontWeight: FontWeight.w600),
                  ),
                  subtitle: Text(
                    post['body'] ?? 'No body',
                    maxLines: 2,
                    overflow: TextOverflow.ellipsis,
                  ),
                ),
              );
            },
          ),
        ),
      ],
    );
  }
}

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Cached Posts',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: PostsScreen(),
    );
  }
}

Step-by-Step Explanation

1.

Choose a caching strategy – Decide between memory cache, disk cache, or both.

2.

Implement the cache layer – Use


          SharedPreferences

,


          Hive

, or


          cache_manager

for disk caching.

3.

Check cache before making network requests – If data is cached and valid, return it immediately.

4.

Save responses to cache – After a successful network request, save the data to cache.

5.

Handle offline scenarios – Fall back to cache when the network is unavailable.

6.

Provide cache management – Allow users to refresh or clear the cache.

Caching Best Practices

✅ Do's

Cache data that is frequently accessed and doesn't change often
Set appropriate cache expiration times (TTL)
Handle offline scenarios gracefully
Provide a way to refresh or clear the cache
Use cache_manager for HTTP caching
Store cache keys consistently
Show cache status to users (e.g., "Cached" badge)

❌ Don'ts

Don't cache sensitive data without encryption
Don't cache indefinitely (always set a TTL)
Don't ignore cache expiration
Don't cache large files without size limits
Don't forget to clear cache when logging out

Common Mistakes

❌ Mistake 1: Not setting cache expiration

Without a TTL (Time To Live), cached data can become stale and show outdated information.

✅ Correct: Set a cache duration

Always set a reasonable expiration time based on how often the data changes.

❌ Mistake 2: Caching everything

Not all data should be cached. Only cache frequently accessed, static, or semi-static data.

✅ Correct: Cache selectively

Cache data that provides value when offline. Avoid caching user-specific or sensitive data.

❌ Mistake 3: Not handling cache read errors

If cached data is corrupted or malformed, the app should fall back gracefully.

✅ Correct: Handle cache errors

Use try-catch when reading from cache and fall back to network requests if it fails.

🎯 The Caching Hierarchy

📦 cache_manager Features

✅ Do's

❌ Don'ts

🎯 Key Takeaway