Slim Cached Network Image #

A Flutter package that wraps cached_network_image to provide a customizable cache manager for potentially better RAM consumption control and default configuration options.

Features #

• Wraps CachedNetworkImage and CachedNetworkImageProvider.
• Provides SlimCacheManager with configurable cache settings (max objects, stale period, image dimensions for caching).
• Allows setting global default cache configurations via SlimCacheManager.setDefaultConfig.
• Allows overriding global configuration per widget instance.
• Queue-based image decoding to prevent browser crashes when loading many images simultaneously (especially on Chrome). See Chromium Issue #40792189.

Getting started #

Add the dependency to your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  slim_cached_network_image: ^0.0.1 # Use the latest version
  # Or point to the path if developing locally
  # slim_cached_network_image:
  #   path: ../path/to/slim_cached_network_image

Then, run flutter pub get.

Usage #

1. Set Default Configuration (Optional) #

You can set global default cache settings, typically in your main.dart before running the app. Important: Ensure Flutter bindings are initialized before setting the configuration by calling WidgetsFlutterBinding.ensureInitialized();.

import 'package:flutter/material.dart';
import 'package:slim_cached_network_image/slim_cached_network_image.dart';

void main() {
  // Ensure Flutter bindings are initialized before using plugins
  WidgetsFlutterBinding.ensureInitialized();

  // Configure the image decode queue (default is 20)
  // This prevents Chrome crashes when loading many images simultaneously
  // See: https://issues.chromium.org/issues/40792189
  SlimImageDecodeConfig.setMaxConcurrentDecodes(20);

  // Configure the default cache settings
  SlimCacheManager.setDefaultConfig(SlimCachedImageConfig( // Use SlimCachedImageConfig
    maxNrOfCacheObjects: 200, // Cache up to 200 images
    stalePeriod: const Duration(days: 14), // Keep images for 14 days
    maxMemWidth: 500, // Cache images with a max width of 500 pixels (disk cache)
    maxMemHeight: 500, // Cache images with a max height of 500 pixels (disk cache)
  ));

  runApp(const MyApp());
}

// ... rest of your app

2. Using the Widget #

Use SlimCachedNetworkImage similarly to CachedNetworkImage. It will use the global configuration by default.

import 'package:flutter/material.dart';
import 'package:slim_cached_network_image/slim_cached_network_image.dart';

class MyImageWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return SlimCachedNetworkImage(
      imageUrl: "https://via.placeholder.com/350x150",
      placeholder: (context, url) => CircularProgressIndicator(),
      errorWidget: (context, url, error) => Icon(Icons.error),
      width: 350,
      height: 150,
      fit: BoxFit.cover,
    );
  }
}

3. Overriding Configuration Per Widget #

You can provide a specific SlimCacheConfig to an individual widget instance.

SlimCachedNetworkImage(
  imageUrl: "https://via.placeholder.com/200",
  cacheConfig: SlimCacheConfig(
    maxWidth: 200, // Specific config for this image
    maxHeight: 200,
    stalePeriod: const Duration(days: 1), // Shorter cache duration
  ),
  placeholder: (context, url) => CircularProgressIndicator(),
  errorWidget: (context, url, error) => Icon(Icons.error),
  width: 200,
  height: 200,
)

4. Using the Image Provider #

Use SlimCachedNetworkImageProvider where an ImageProvider is needed, for example, with Image or DecorationImage.

Image(
  image: SlimCachedNetworkImageProvider(
    "https://via.placeholder.com/100",
    // Optional: Provide specific config for this provider instance
    // cacheConfig: SlimCacheConfig(maxWidth: 100, maxHeight: 100),
  ),
)

// Or in a BoxDecoration
// Or in a BoxDecoration
Container(
  decoration: BoxDecoration(
    image: DecorationImage(
      image: SlimCachedNetworkImageProvider("https://via.placeholder.com/400"),
      fit: BoxFit.cover,
    ),
  ),
)

5. Image Decode Queue (Preventing Browser Crashes) #

When loading many images simultaneously (~2000+), browsers like Chrome can crash due to concurrent image decoding limits. This package includes a queue system that limits concurrent image decode operations.

Default behavior: Maximum 20 concurrent image decodes

Configure the queue:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Set the maximum concurrent decode operations (default is 20)
  SlimImageDecodeConfig.setMaxConcurrentDecodes(20);
  
  runApp(const MyApp());
}

Monitor queue statistics (useful for debugging):

// Get current queue stats
Map<String, int> stats = SlimImageDecodeConfig.getQueueStats();
print('Active decodes: ${stats['activeDecodes']}');
print('Pending in queue: ${stats['pendingDecodes']}');
print('Max concurrent: ${stats['maxConcurrent']}');

This feature is especially important for web applications and helps prevent the Chrome crash described in Chromium Issue #40792189.

```