Firebase_Cached_Image

Cache Manager and Cached ImageProvider for Firebase Cloud Storage Objects.

Set up

Setup firebase (https://firebase.google.com/docs/flutter/setup).

Web Support

Web support is experimental. To enable it, add the following line in your main() function:

FirebaseCacheManagerConfig.webSupport = true;

On the web, It uses indexed_db for caching the files. All the files are directly saved to the browser's IndexedDB store. Read more about IndexedDB here (https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).

Usage

Firebase Image Provider

To display an image from Firebase Cloud Storage, use FirebaseImageProvider as the ImageProvider for the Flutter Image widget.

Image(
  image: FirebaseImageProvider(
    FirebaseUrl("gs://bucket_f233/logo.jpg")
  ),
),

You can declare FirebaseUrl in following ways:

FirebaseUrl("gs://bucket_f233/logo.jpg")
FirebaseUrl("https://firebasestorage.googleapis.com/b/bucket/o/logo.jpg")
FirebaseUrl.fromReference(FirebaseStorage.instance.ref("images/image.jpg"));

Cache Options

Customize caching behavior with CacheOptions:

Image(
  image: FirebaseImageProvider(
    FirebaseUrl("gs://bucket_f233/logo.jpg"),
    options: CacheOptions(
      checkIfFileUpdatedOnServer: false,
      source: Source.cacheServer,
    ),
  ),
),

Default behavior: Load from cache if available; otherwise fetch from server and then cache.
Always fetch latest from server:
```
source: Source.server,
```
Fetch from server only if updated since last fetch:
```
checkIfFileUpdatedOnServer: true,
```

Note: Image update checks require fetching metadata (last modified timestamp) from Firebase Storage.
This is a Class B operation in Google Cloud Storage, which may incur charges after 50,000 free operations per month. Pricing details.

Firebase Cache Manager

For more control and support beyond images (e.g., docs, videos), use FirebaseCacheManager.

Download and Cache a File

Not supported on web.

final file = await FirebaseCacheManager().getSingleFile(
  FirebaseUrl("gs://bucket_f233/doc.docx"),
);
print(file); // Local cached file path (useful for sharing/reading)

You can also use getSingleObject method to get the file as bytes:

Supported on web.

final cachedObject = await FirebaseCacheManager().getSingleObject(
  FirebaseUrl("gs://bucket_f233/doc.docx"),
);

print(cachedObject.rawBytes); // Uint8List of file bytes

Pre-cache a File

Pre-download files you know will be needed soon (e.g., profile pictures at app start):

await FirebaseCacheManager().preCache(
  FirebaseUrl("gs://bucket_f233/profile_pic.jpg"),
);

Refresh a Cached File

Update a cached file if it has changed on the server:

await FirebaseCacheManager().refreshCachedFile(
  FirebaseUrl("gs://bucket_f233/profile_pic.jpg"),
);

Copy a Local File to Cache

Avoid re-downloading by copying an existing local file into the cache.
Not supported on web.

final filePath = "/storage/file.jpg";
final cachedFilePath = await FirebaseCacheManager().copyToCache(
  FirebaseUrl("gs://bucket_f233/profile_pic.jpg"),
  filePath,
);

Delete a Cached File

await FirebaseCacheManager().delete(
  FirebaseUrl("gs://bucket_f233/logo.jpg"),
);

Clear Cache

// Clear entire cache (Supported on web)
await FirebaseCacheManager().clearCache();

// Clear files older than 20 days (Not supported on web)
await FirebaseCacheManager().clearCache(modifiedBefore: Duration(days: 20));

Custom Sub-Directory

Save cached files in a custom subdirectory inside the system’s temporary directory.
Default: "flutter_cached_image"

final manager = FirebaseCacheManager(subDir: "profile_pictures");

This allows organizing cached files by category:

final profilePicturesCacheManager = FirebaseCacheManager(subDir: "profile_pictures");
final postsCacheManager = FirebaseCacheManager(subDir: "posts");

// Clear only "posts" cache
await postsCacheManager.clearCache();

Platform Support

Method	Mobile	Web
`getSingleFile()`	✅ Supported	✅ Supported
`preCache()`	✅ Supported	✅ Supported
`refreshCachedFile()`	✅ Supported	✅ Supported
`copyToCache()`	✅ Supported	❌ Not Supported
`delete()`	✅ Supported	✅ Supported
`clearCache()` (all files)	✅ Supported	✅ Supported
`clearCache(modifiedBefore)`	✅ Supported	❌ Not Supported