expo-cached-image

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


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

``bash


Using npm

npm install expo-cached-image

Using yarn

yarn add expo-cached-image

Using expo

npx expo install expo-cached-image
`

Basic Usage

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

const MyComponent = () => {
return (
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
color="#999999"
size="small"
style={{ flex: 1, justifyContent: "center" }}
/>
)}
style={{ width: 200, height: 200 }}
resizeMode="contain"
/>
)
}
`

API Reference

$3

#### 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 |

$3

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

#### Methods

##### addToCache
`typescript
const uri = await CacheManager.addToCache({
file: '/path/to/local/file',
key: 'unique-key'
})
`

##### getCachedUri
`typescript
const uri = await CacheManager.getCachedUri({
key: 'unique-key'
})
`

##### downloadAsync
`typescript
const result = await CacheManager.downloadAsync({
uri: 'https://example.com/image.jpg',
key: 'unique-key',
options: {
headers: {
'Authorization': 'Bearer token'
}
}
})
`

##### getMetadata
`typescript
const metadata = await CacheManager.getMetadata({
key: 'unique-key'
})

if (metadata) {
console.log('File exists:', metadata.exists)
console.log('File size:', metadata.size, 'bytes')
console.log('Last modified:', metadata.modificationTime)
console.log('File path:', metadata.uri)
} else {
console.log('File not found or error occurred')
}
`

Returns metadata for a cached item, including file existence, size, modification time, and file path. Returns null if the file doesn't exist or an error occurs.

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

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

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

return (
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 ? (

) : (

)
}
/>
);
};
``

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

- github - Photo sharing react-native source code.
- WiSaw on the web - here is how it looks on the web.
- install iOS app
- install Android app

Support

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