packages.dart/experimental/http_get_cache/README.md

http_get_cache

A robust, HTTP-compliant caching library for Flutter and Dart. http_get_cache wraps the standard http package to automatically cache GET requests based on Cache-Control, Vary, ETag, and Last-Modified headers.

It uses SQLite (via drift) for metadata storage and the file system for caching response bodies, ensuring separate, non-blocking storage.

Features

• 🚀 HTTP Client Wrapper: Drop-in replacement for http.Client.
• 💾 Persistent Caching: Stores cache data in SQLite and files on disk.
• 🌍 Vary Header Support: Caches variations of responses based on request headers (e.g., User-Agent).
• 🔄 Standard Compliant: Respects max-age, no-cache, no-store, stale-while-revalidate, and more.
• 🖼️ HttpImageProvider: A cached ImageProvider for Flutter.
• 📱 Cross Platform: Works on Android, iOS, macOS, Windows, and Linux.

Warning

This package does not support Web. On Web, http_get_cache logic is disabled. You should use the fetch_client package instead, which leverages the browser's native caching capabilities.

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  http_get_cache: ^latest_version

Usage

1. Initialization

You must initialize the cache database before making requests.

Flutter:

import 'package:flutter/material.dart';
import 'package:http_get_cache/http_get_cache_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize caching with default paths
  await initFlutterHttpGetCache();
  
  runApp(const MyApp());
}

Dart (Standalone):

import 'package:http_get_cache/http_get_cache.dart';

void main() async {
  await initHttpGetCache(
    cachePath: './.cache',
    databasePath: './.db',
  );
}

2. Making Requests

Use the global httpClient() helper to get a Client that handles caching automatically.

import 'package:http_get_cache/http_get_cache.dart'; 

Future<void> fetchData() async {
  final client = httpClient();
  
  // This request will be cached if headers allow it
  final response = await client.get(Uri.parse('https://jsonplaceholder.typicode.com/posts/1'));
  
  if (response.statusCode == 200) {
    print('Response: ${response.body}');
  }
  
  client.close();
}

3. Caching Images in Flutter

Use HttpImageProvider to load and cache images efficiently.

import 'package:flutter/material.dart';
import 'package:http_get_cache/http_image_provider.dart';

class MyImageWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Image(
      image: HttpImageProvider(
        Uri.parse('https://via.placeholder.com/150'),
      ),
    );
  }
}

How It Works

This package implements most of RFC 7234.

1. Cache-Control: Checks max-age to determine if a cached response is still fresh.
2. Stale-While-Revalidate: Can return stale content while updating the cache in the background.
3. Vary: Stores distinct cache entries if the server response includes a Vary header (e.g. varying by Accept-Language).
4. Revalidation: Uses ETag and Last-Modified to check with the server if the cached content has changed (Returns 304 Not Modified if valid).

Web Support

This package is designed for native platforms where persistent HTTP caching is not built-in.

On Web, browsers handle caching automatically via the Fetch API. Using this package on Web adds unnecessary overhead as the internal caching logic is disabled (kIsWeb checks).

Recommendation: Use fetch_client directly for Web applications.

Advanced Usage

Custom Client

You can use a custom inner client (e.g. http.Client, RetryClient) with HttpGetCache.

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

void main() async {
  final db = await initFlutterHttpGetCache();
  final store = SqliteHttpCacheStore(db);
  
  final client = HttpGetCache(
    http.Client(), // Inner client
    store,
  );
  
  // Use client...
}

Native Networking

To improve performance on mobile devices (e.g. HTTP/3 support), you can provide a native HTTP client to httpClient:

1. Add dependencies: cronet_http and cupertino_http.
2. Pass the native client as innerClient.

import 'dart:io';
import 'package:cronet_http/cronet_http.dart';
import 'package:cupertino_http/cupertino_http.dart';
import 'package:http/http.dart';
import 'package:http_get_cache/http_get_cache.dart';

Client getNativeClient() {
  if (Platform.isAndroid) {
    return CronetClient.defaultCronetEngine();
  }
  if (Platform.isIOS || Platform.isMacOS) {
    return CupertinoClient.defaultSessionConfiguration();
  }
  return Client();
}

void main() async {
  await initFlutterHttpGetCache();

  final client = httpClient(
    innerClient: getNativeClient(),
  );
}

Platform Support

Platform	Support	Storage
Android	✅	SQLite + File System
iOS	✅	SQLite + File System
macOS	✅	SQLite + File System
Windows	✅	SQLite + File System
Linux	✅	SQLite + File System
Web	⚠️	Not Supported (Use fetch_client)