React Native Image Cache HOC
React Native Higher Order Component that adds advanced caching functionality to the react native Image component.
Features
- Drop in Replacement for native <Image> component.
- Automatically Cache remote image files to local filesystem to increase performance.
- Automatically Persist remote image files to local filesystem forever with a simple component prop flag.
Installation
$ npm install --save react-native-image-cache-hoc
Or
$ yarn add react-native-image-cache-hoc
Then, because this package has a depedency on rn-fetch-blob you will need to link this native package by running:
$ react-native link rn-fetch-blob
Linking rn-fetch-blob should only be done once, reinstalling node_modules with npm or yarn does not require running the above command again.
To troubleshoot linking, refer to the rn-fetch-blob installation instructions.
Usage
React Native Image Cache HOC creates an advanced image component, <CacheableImage>, that is a drop in replacement for the standard <Image> component.
Differences between the advanced image component and standard image component API are as follows:
- Modified "source" Prop: The advanced component "source" prop only accepts a web accessible url (there's no reason to use this library to render files that already exist on the local filesystem), and it does NOT accept an array of urls.
- New "permanent" Prop: The new, optional (defaults to False), "permanent" prop determines if the image file should be stored forever on the local filesystem instead of written to a temperary cache that is subject to occasional pruning.
- New "placeholder" Prop: The new, optional (defaults to standard Image component), "placeholder" prop determines component to render while remote image file is downloading.
TL;DR: To cache image files for performance, simply use <CacheableImage> as a drop in replacement for <Image>. To store files permanently add a permanent={true} prop to <CacheableImage>.
;; ; /*** Pass the native <Image> component into imageCacheHoc() to create the advanced image component <CacheableImage>.* * imageCacheHoc() takes an options object as the second parameter (refer to options section of README.md)*/const CacheableImage = ; <{}> { return <View style=stylescontainer> <Text style=styleswelcome>Welcome to React Native!</Text> <CacheableImage style=stylesimage source=uri: 'https://i.redd.it/rc29s4bz61uz.png' permanent=false /> </View> ; } const styles = StyleSheet;
Options
React Native Image Cache HOC accepts an options object in order to tweak standard functionality.
;
Using Loading Placeholders
React Native Image Cache HOC allows you to easily supply any component to be used as a placeholder while the remote image file is downloading. While the default placeholder should be great for many use cases, you can easily use your own to match the style of the rest of your app.
const styles = StyleSheet; // This placeholder object will be used as a placeholder component for all instances of <CacheableImage> // unless individual <CacheableImage> uses "placeholder" prop to override this default.const defaultPlaceholderObject = component: ActivityIndicator props: style: stylesactivityIndicatorStyle ; // We will use this placeholder object to override the default placeholder.const propOverridePlaceholderObject = component: Image props: style: stylesimage source: ; const CacheableImage = ; <{}> { return <View style=stylescontainer> <Text style=styleswelcome>Welcome to React Native!</Text> <CacheableImage style=stylesimage source=uri: 'https://i.redd.it/rc29s4bz61uz.png' /> <CacheableImage style=stylesimage source=uri: 'https://i.redd.it/hhhim0kc5swz.jpg' placeholder=propOverridePlaceholderObject /> <CacheableImage style=stylesimage source=uri: 'https://i.redd.it/17ymhqwgbswz.jpg' /> </View> ; }
Static Methods
The CacheableImage class returned by React Native Image Cache HOC includes a couple of static methods for convenience.
CacheableImage.cacheFile(url, permanent)
Use this method if you need to download a file to the local filesystem prior to rendering <CacheableImage> for some reason (perhaps to pre-warm the local cache). If calling this method repeatedly to cache a long list of files, be sure to use a queue and limit concurrency so your app performance does not suffer.
;const CacheableImage = ;CacheableImage ; CacheableImage ;
CacheableImage.flush()
Delete all locally stored image files created by react-native-image-cache-hoc (cache AND permanent). Calling this method will cause a performance hit on your app until the local files are rebuilt.
;const CacheableImage = ;CacheableImage ;
Jest Test Support
React Native Image Cache HOC must be run in a native environment to work correctly. As a result it will create issues in your jest tests unless you mock it. Since this module is an HOC that adds additional functionality to the standard <Image> component, it can be easily mocked with a function that returns the standard <Image> component.
Add the following to your jest mocks:
jest;
Warning
iOS only allows requests to https urls. If you need to load image files using http you will need to make additional react native config changes.
By default, iOS will block any request that's not encrypted using SSL. If you need to fetch from a cleartext URL (one that begins with http) you will first need to add an App Transport Security exception. If you know ahead of time what domains you will need access to, it is more secure to add exceptions just for those domains; if the domains are not known until runtime you can disable ATS completely. Note however that from January 2017, Apple's App Store review will require reasonable justification for disabling ATS.