Skip to Content
DocsAdd WebF To FlutterAdvanced TopicsCaching

Caching

WebF provides sophisticated caching for both HTTP resources and JavaScript bytecode to improve performance and enable offline capabilities.

HTTP Cache Configuration

Configure global HTTP caching behavior for all WebF controllers:

// Set global cache mode
WebF.setHttpCacheMode(HttpCacheMode.cacheFirst);  // Default: cacheFirst
 
// Available modes:
// - HttpCacheMode.cacheFirst: Check cache first, then network
// - HttpCacheMode.networkOnly: Always fetch from network
// - HttpCacheMode.cacheOnly: Only use cache (fail if not cached)

Cache Modes Explained

HttpCacheMode.cacheFirst (Default)

Best for most applications. Checks cache first for faster loading, falls back to network if not cached.

Use when:

  • You want fast loading times
  • Content doesn’t change frequently
  • Offline capability is desired

HttpCacheMode.networkOnly

Always fetches from network, bypasses cache entirely.

Use when:

  • Content must always be fresh
  • Testing and development
  • Dynamic content that changes frequently

HttpCacheMode.cacheOnly

Only uses cached content, fails if resource not in cache.

Use when:

  • Building offline-first applications
  • Resources are pre-cached during installation
  • You want to guarantee no network requests

Clearing Caches

Clear cached content when needed:

// Clear all caches (HTTP + bytecode)
await WebF.clearAllCaches();
 
// Or use controller-specific cache clearing
HttpCacheController.clearMemoryCache();

When to Clear Caches

  • App updates: Clear caches after deploying new versions
  • User logout: Clear sensitive cached data
  • Settings option: Provide users a way to clear cache
  • Storage management: Free up device storage when needed

Example with version checking:

Future<void> checkAndClearCache() async {
  final prefs = await SharedPreferences.getInstance();
  final currentVersion = '1.2.0';
  final cachedVersion = prefs.getString('app_version');
 
  if (cachedVersion != currentVersion) {
    await WebF.clearAllCaches();
    await prefs.setString('app_version', currentVersion);
    print('Cache cleared for new version: $currentVersion');
  }
}

Custom HTTP Client Adapters

WebF uses Dio for HTTP requests and allows you to customize the HTTP client with custom adapters. This is useful for advanced networking features like custom caching strategies, protocol support, or request/response interceptors.

Example: Using Cronet on Android

Cronet provides advanced networking features including HTTP/2, QUIC, and built-in caching:

WebFController(
  networkOptions: WebFNetworkOptions(
    android: WebFNetworkOptions(
      httpClientAdapter: () async {
        final cacheDir = await HttpCacheController.getCacheDirectory(
          Uri.parse('https://myapp.com/')
        );
 
        final cronetEngine = CronetEngine.build(
          cacheMode: CacheMode.disk,
          cacheMaxSize: 50 * 1024 * 1024,  // 50MB
          enableBrotli: true,
          enableHttp2: true,
          enableQuic: true,
          storagePath: cacheDir,
        );
 
        return CronetAdapter(cronetEngine);
      },
      enableHttpCache: false,  // Let Cronet handle caching
    ),
  ),
)

When to Use Custom HTTP Adapters

Advanced protocol support:

  • HTTP/2 and HTTP/3 (QUIC)
  • Brotli compression
  • Custom protocols

Platform-specific optimizations:

  • Cronet on Android
  • NSURLSession on iOS
  • Native networking stacks

Custom configurations:

  • SSL/TLS settings
  • Request/response logging
  • Custom retry strategies
  • Connection pooling

Monitoring:

  • Network performance tracking
  • Request/response inspection
  • Error logging

Cronet Benefits

Performance:

  • Connection pooling across apps
  • Automatic protocol negotiation
  • Better mobile network handling

Modern protocols:

  • HTTP/2 support
  • HTTP/3 (QUIC) support
  • Brotli compression

Built-in features:

  • Intelligent caching
  • Connection migration
  • Network quality estimation

Cache Strategy Examples

Aggressive Caching for Static Assets

void main() {
  // Set aggressive caching for static content
  WebF.setHttpCacheMode(HttpCacheMode.cacheFirst);
 
  WebFControllerManager.instance.initialize(
    WebFControllerManagerConfig(
      maxAliveInstances: 5,
      maxAttachedInstances: 3,
    ),
  );
 
  runApp(MyApp());
}

Network-First for Dynamic Content

void main() {
  // Always fetch fresh content
  WebF.setHttpCacheMode(HttpCacheMode.networkOnly);
 
  WebFControllerManager.instance.initialize(
    WebFControllerManagerConfig(
      maxAliveInstances: 5,
      maxAttachedInstances: 3,
    ),
  );
 
  runApp(MyApp());
}

Offline-First Application

void main() {
  // Only use cached content
  WebF.setHttpCacheMode(HttpCacheMode.cacheOnly);
 
  WebFControllerManager.instance.initialize(
    WebFControllerManagerConfig(
      maxAliveInstances: 5,
      maxAttachedInstances: 3,
    ),
  );
 
  runApp(MyApp());
}

HTTP Cache Headers

WebF respects standard HTTP cache headers:

Cache-Control: max-age=3600        # Cache for 1 hour
Cache-Control: no-cache            # Revalidate with server
Cache-Control: no-store            # Don't cache
ETag: "abc123"                     # Content version
Last-Modified: Wed, 21 Oct 2025    # Last modification time

Configure your web server to set appropriate cache headers for optimal performance.

Best Practices

  1. Set Appropriate Cache Mode: Choose the right cache mode for your use case (cacheFirst for most apps).

  2. Clear Cache on Updates: Clear caches when deploying new app versions to ensure users get fresh content.

  3. Use Cache Headers: Configure your server to send proper Cache-Control headers for optimal caching behavior.

  4. Monitor Cache Size: On mobile devices, be mindful of storage usage. Consider limiting cache size with Cronet.

  5. Test Offline: Verify your app works correctly in offline mode if using cacheFirst or cacheOnly modes.

  6. Platform-Specific Adapters: Use Cronet on Android for better performance and modern protocol support.

Troubleshooting

Cache Not Working

  • Check that HttpCacheMode is set correctly
  • Verify server sends proper Cache-Control headers
  • Check storage permissions on device

Stale Content

  • Clear cache: WebF.clearAllCaches()
  • Use HttpCacheMode.networkOnly during development
  • Implement version checking to auto-clear cache

Large Cache Size

  • Configure cacheMaxSize in Cronet
  • Clear cache periodically
  • Use appropriate cache headers (shorter max-age)

Next Steps

ThemingAPI Reference