Cached Network Image — Community Edition

A Flutter library to show images from the internet and keep them in the cache directory.

This is the actively maintained, high-performance community fork of cached_network_image.

---

📖 The Story: Why this fork?

The original cached_network_image package by Baseflow is a titan in the Flutter ecosystem, used by millions. However, it has been effectively unmaintained since August 2024, leaving over 300 issues unresolved, including critical memory leaks and scroll performance bugs.

As the Flutter ecosystem evolved, the original architecture began to show its age. It relied on sqflite for cache management—a heavy, SQL-based solution that requires platform channels to communicate with native code. For a simple task like "checking if an image exists," this overhead caused UI jank in heavy lists.

We created the Community Edition (_ce) to fix this.

We didn't just fork it to merge dependabot PRs. We re-engineered the caching layer.

⚡ The Architectural Shift: SQLite vs. Hive

We replaced the heavy sqflite dependency with hive_ce.

• Old Way (sqflite): serialized data → Platform Channel → Java/Obj-C → SQLite → Disk. (Slow, blocking).
• New Way (hive_ce): Dart Memory → Direct Disk Access. (Instant, non-blocking).

The result? Zero-jank scrolling.

🚀 Benchmarks

We benchmarked the cache metadata operations (checking, writing, and deleting cache entries) on an iPhone Simulator. The results speak for themselves:

Operation	Payload Size	Original (sqflite)	CE (hive_ce)	Improvement
Read (Hit Check)	10 KB	16 ms	2 ms	⚡ 8.00x Faster
Write (New Image)	10 KB	116 ms	29 ms	🚀 4.00x Faster
Delete (Cleanup)	10 KB	55 ms	19 ms	🧹 2.89x Faster
Read (Large)	1 MB	8 ms	1 ms	⚡ 8.00x Faster

Note: "Read" is the most critical operation for scrolling performance, as every list item checks the cache before rendering.

---

🛠 Features

• Drop-in Replacement: 99% API compatible with the original package.
• High Performance: Powered by hive_ce for instant cache lookups.
• Actively Maintained: Regular updates, bug fixes, and community-driven roadmap.
• True Web Support: Unlike the original package, CE provides full, persistent image caching on the Web via IndexedDB (hive_ce), completely avoiding RAM freezes by using native image decoding sizes.

📦 Installation

Add cached_network_image_ce to your pubspec.yaml:

dependencies:
  cached_network_image_ce: ^1.0.0

💻 How to use

The API is identical to the original package. You can use CachedNetworkImage directly or via ImageProvider.

Basic Usage with Placeholder

import 'package:cached_network_image_ce/cached_network_image_ce.dart';

CachedNetworkImage(
  imageUrl: '[https://via.placeholder.com/350x150](https://via.placeholder.com/350x150)',
  placeholder: (context, url) => CircularProgressIndicator(),
  errorWidget: (context, url, error) => Icon(Icons.error),
),

With Progress Indicator

CachedNetworkImage(
  imageUrl: '[https://via.placeholder.com/350x150](https://via.placeholder.com/350x150)',
  progressIndicatorBuilder: (context, url, downloadProgress) =>
      CircularProgressIndicator(value: downloadProgress.progress),
  errorWidget: (context, url, error) => Icon(Icons.error),
),

Advanced Usage (ImageBuilder)

Use this when you need an ImageProvider for things like DecorationImage:

CachedNetworkImage(
  imageUrl: '[https://via.placeholder.com/200x150](https://via.placeholder.com/200x150)',
  imageBuilder: (context, imageProvider) => Container(
    decoration: BoxDecoration(
      image: DecorationImage(
        image: imageProvider,
        fit: BoxFit.cover,
        colorFilter: ColorFilter.mode(Colors.red, BlendMode.colorBurn),
      ),
    ),
  ),
  placeholder: (context, url) => CircularProgressIndicator(),
  errorWidget: (context, url, error) => Icon(Icons.error),
),

Direct ImageProvider Usage

Image(image: CachedNetworkImageProvider(url))

❓ FAQ

Q: Will I lose my users' existing cache if I migrate? A: Yes. Because we switched the storage engine from SQLite to Hive, the old cache files will be ignored. Users will re-download images once as they browse. This is a one-time migration cost for a permanent performance gain.

Q: My app crashes/pauses on errors? A: In Debug mode, Flutter may pause on exceptions even if they are caught. This is expected behavior for network errors (404s). In Release mode, these are handled silently by the errorWidget.

Q: Why is web caching slower or using Hive for image bytes? A: On Mobile & Desktop (IO), this package stores image bytes directly on the incredibly fast native file system, and uses Hive only for metadata. The Web platform, however, lacks a native file system. Therefore, for web we use hive_ce to store both metadata and the actual image bytes in IndexedDB. Serializing large byte arrays in and out of IndexedDB introduces overhead that isn't present on IO. Alternative: If persistent caching across sessions isn't critical for your web users, consider conditionally using the standard Image.network on the web, which relies on the browser's built-in memory/HTTP caching to achieve faster decoding.

🤝 Contributing

We welcome contributions! If you want to help maintain this essential package, please check the CONTRIBUTING.md.

📄 License

This project is licensed under the MIT License.