react-native-fast-image

FastImage treats image URLs as immutable. This means the library assumes that the content located at a specific URL will never change.

If an image changes (for example, a user updates their profile picture), the backend should provide a new URL for that image. If you attempt to use the same URL for a different image, FastImage will continue to show the old cached version because it believes the content at that URL is unchanged.

Recommended Workflow for Dynamic Images:

1. The backend provides a unique URL for the resource (e.g., .../user/123/profile_v2.jpg).
2. FastImage fetches and caches this URL.
3. When the resource updates, the backend provides a new URL (e.g., .../user/123/profile_v3.jpg).
4. FastImage treats this as a new request and fetches the updated image.

FastImage manages its own cache lifecycle automatically. You generally do not need to manually manage or clear the cache.

As the application is used, the cache grows. Once the cache reaches its maximum size, the library automatically purges the least frequently used (LFU) images to make room for new ones.

To run the example project, you must first ensure your React Native environment is set up according to the official React Native documentation. The process involves starting the Metro bundler and then launching the application on an emulator or simulator.

1. Start the Metro Server

Open a terminal at the root of the project and run:

# using npm
npm start

# OR using Yarn
yarn start

2. Start the Application

Open a new terminal window (keeping Metro running in the first one) and run the command for your target platform:

For Android:

# using npm
npm run android

# OR using Yarn
yarn android

For iOS:

# using npm
npm run ios

# OR using Yarn
yarn ios

# Start Metro
npm start

# Start Android
npm run android

# Start iOS
npm run ios

To install FastImage in your project, use either yarn or npm. Note that you must be using React Native 0.60.0 or higher. After installing the package, you must install the iOS dependencies using CocoaPods.

# Using yarn
yarn add @d11/react-native-fast-image
cd ios && pod install

# Or using npm
npm install @d11/react-native-fast-image
cd ios && pod install

This project uses Yarn 3.6.4. If your local Yarn version is different, use corepack to activate the correct version.

1. Enable corepack: corepack enable
2. Check version: yarn -v (should return 3.6.4)
3. If the version is incorrect, run: corepack prepare yarn@3.6.4 --activate

If you are not using a clean React Native installation, you may need to override the Android SDK and dependency versions used by react-native-fast-image. The library is designed to detect project-wide properties defined in your root build.gradle file within the ext block. By setting these properties, you can ensure the library uses the same versions as the rest of your Android project.

To apply these changes, add or modify the following keys in the ext block of your root build.gradle file:

/**
 + Project-wide Gradle configuration properties
 */
ext {
    // You can use any of these to change project-wide versions:
    // compileSdkVersion   = 26
    // targetSdkVersion    = 26
    // minSdkVersion       = 16
    // buildToolsVersion   = "26.0.3"
    // supportLibVersion   = "27.1.1"
    // glideVersion        = "4.7.1"
}

To test code changes using the included example app, ensure your environment meets the following requirements:

• Node.js: version 18 or higher
• Java: version 21
• Yarn: version 3.6.4

Follow these steps in the repository root to prepare the environment and run the example app on Android or iOS.

# 1. Enable corepack and ensure Yarn 3.6.4 is active
corepack enable
corepack prepare yarn@3.6.4 --activate

# 2. Install dependencies in the repo root
yarn

# 3. Run on Android
yarn example android

# OR Run on iOS
cd ReactNativeFastImageExample/ios
bundle install
pod install
cd ../..
yarn example ios

After modifying code in App.tsx, you can reload the application to reflect changes using the following platform-specific methods:

• Android: Press the <kbd>R</kbd> key twice or open the Developer Menu (<kbd>Ctrl</kbd> + <kbd>M</kbd> on Windows/Linux, or <kbd>Cmd ⌘</kbd> + <kbd>M</kbd> on macOS) and select "Reload".
• iOS: Press <kbd>Cmd ⌘</kbd> + <kbd>R</kbd> within the iOS Simulator.

If your application does not require SVG support, you can disable SVG decoders via an environment variable to reduce native dependencies and the final binary size. This must be done before running pod install on iOS or before building on Android.

# iOS (before running CocoaPods)
export DISABLE_SVG=1 
cd ios && pod install

# Android (before building)
export DISABLE_SVG=1
yarn android

If your Android application already uses a custom AppGlideModule (via Glide), you must prevent @d11/react-native-fast-image from including its own AppGlideModule to avoid build conflicts.

To do this, add the excludeAppGlideModule flag to your android/build.gradle file within the project.ext block.

project.ext {
    excludeAppGlideModule = true
}

If you are using ProGuard for code shrinking and obfuscation in your Android build, you must add the following rules to android/app/proguard-rules.pro to prevent FastImage and its dependencies from being stripped.

-keep public class com.dylanvann.fastimage.* {*;}
-keep public class com.dylanvann.fastimage.** {*;}
-keep public class * implements com.bumptech.glide.module.GlideModule
-keep public class * extends com.bumptech.glide.module.AppGlideModule
-keep public enum com.bumptech.glide.load.ImageHeaderParser$** {
  **[] $VALUES;
  public *;
}