expo-cached-image
TypeScript icon, indicating that this package has built-in type declarations

52.0.40 • Public • Published

expo-cached-image

Super fast and secure cached image component for React Native applications built with Expo.

npm version License: MIT

Features

  • 🚀 Fast image loading with local caching
  • 🔒 Secure file handling and sanitized cache keys
  • ⏱️ Configurable cache expiration
  • 🔄 Automatic cache cleanup
  • 📱 Full TypeScript support
  • 🎨 Customizable placeholder content

Installation

# Using npm
npm install expo-cached-image

# Using yarn
yarn add expo-cached-image

# Using expo
npx expo install expo-cached-image

Basic Usage

import CachedImage from 'expo-cached-image'
import { ActivityIndicator } from 'react-native'

const MyComponent = () => {
  return (
    <CachedImage
      source={{ 
        uri: 'https://example.com/image.jpg',
        headers: { 'Authorization': 'Bearer your-token' }, // Optional
        expiresIn: 86400, // Optional: Cache expiration in seconds (24 hours)
      }}
      cacheKey="unique-image-key" // Required: Unique identifier for the image
      placeholderContent={( // Optional: Component to show while loading
        <ActivityIndicator 
          color="#999999"
          size="small"
          style={{ flex: 1, justifyContent: "center" }}
        />
      )}
      style={{ width: 200, height: 200 }}
      resizeMode="contain"
    />
  )
}

API Reference

CachedImage Component

Props

Prop Type Required Description
source ImageSource Yes Image source object containing uri, optional headers and expiration
cacheKey string Yes Unique identifier for caching the image
placeholderContent ReactNode No Component to display while image is loading
...ImageProps ImageProps No All props from React Native's Image component

ImageSource Properties

Property Type Required Description
uri string Yes URL of the image to load and cache
headers object No Request headers for image download
expiresIn number No Cache expiration time in seconds

CacheManager API

import { CacheManager } from 'expo-cached-image'

Methods

addToCache
const uri = await CacheManager.addToCache({
  file: '/path/to/local/file',
  key: 'unique-key'
})
getCachedUri
const uri = await CacheManager.getCachedUri({
  key: 'unique-key'
})
downloadAsync
const result = await CacheManager.downloadAsync({
  uri: 'https://example.com/image.jpg',
  key: 'unique-key',
  options: {
    headers: {
      'Authorization': 'Bearer token'
    }
  }
})

Security Considerations

  1. Always use HTTPS URLs for image sources
  2. Cache keys are automatically sanitized to prevent path traversal and other filesystem-related vulnerabilities
    • Only alphanumeric characters, dashes, and underscores are allowed
    • Keys are limited to 100 characters
    • Leading dashes and periods are replaced with underscores
  3. Implement proper token/credentials management for authenticated requests
  4. Be mindful of storage space when caching large images
  5. Consider implementing cache size limits in your application

Best Practices

  1. Use meaningful and unique cache keys
    • Keys will be automatically sanitized, but it's best to use simple alphanumeric identifiers
    • Example: "user-123-profile-image" or "product_456_thumbnail"
  2. Implement placeholder content for better UX
  3. Set appropriate cache expiration times
  4. Handle errors gracefully
  5. Clean up unused cached images periodically

Example with Error Handling

const SecureImageComponent = () => {
  const [error, setError] = useState(false);

  const handleError = () => {
    setError(true);
    // Implement your error handling logic
  };

  return (
    <CachedImage
      source={{
        uri: 'https://secure-site.com/image.jpg',
        headers: {
          'Authorization': 'Bearer token',
          'Accept': 'image/*'
        },
        expiresIn: 3600 // 1 hour
      }}
      cacheKey="secure-image-1"
      onError={handleError}
      placeholderContent={
        error ? (
          <ErrorPlaceholder />
        ) : (
          <LoadingPlaceholder />
        )
      }
    />
  );
};

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Projects Using expo-cached-image

  • WiSaw - Photo sharing platform

Support

If you're having any problem, please raise an issue on GitHub.

Package Sidebar

Install

npm i expo-cached-image

Weekly Downloads

882

Version

52.0.40

License

MIT

Unpacked Size

21.4 kB

Total Files

9

Last publish

Collaborators

  • echowaves