@candlefinance/faster-image

When working with the FasterImageExample project, the metro.config.js is configured to prevent multiple versions of peer dependencies from being loaded. It achieves this by:

1. Blacklisting peer dependencies found in the project root's node_modules using resolver.blacklistRE.
2. Aliasing those same dependencies to the versions located within the example directory's node_modules using resolver.extraNodeModules.

This ensures that the bundler uses a single, consistent version of each peer dependency required by @candlefinance/faster-image.

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const path = require('path');
const escape = require('escape-string-regexp');
const exclusionList = require('metro-config/src/defaults/exclusionList');
const pak = require('../package.json');

const root = path.resolve(__dirname, '..');
const modules = Object.keys({ ...pak.peerDependencies });

const config = {
  watchFolders: [root],

  resolver: {
    // Blocks peerDependencies at the root
    blacklistRE: exclusionList(
      modules.map(
        (m) =>
          new RegExp(`^${escape(path.join(root, 'node_modules', m))}\/.*$`)
      )
    ),

    // Aliases them to the versions in example's node_modules
    extraNodeModules: modules.reduce((acc, name) => {
      acc[name] = path.join(__dirname, 'node_modules', name);
      return acc;
    }, {}),
  },

  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: true,
      },
    }),
  },
};

module.exports = mergeConfig(getDefaultConfig(__dirname), config);

The following props are available for the FasterImageView component. Note that some props are platform-specific (iOS or Android only).

| Prop | Type | Default | Description |
| ------------------------- | --------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------- |
| url | string | | The URL of the image |
| style | object | | The style of the image |
| resizeMode | string | contain | The resize mode of the image |
| thumbhash | string | | The thumbhash of the image as a base64 encoded string to show while loading (Android not tested) |
| blurhash | string | | The blurhash of the image to show while loading (iOS only) |
| showActivityIndicator | boolean | false | Whether to show the UIActivityIndicatorView indicator when the image is loading (iOS only) |
| activityColor | ColorValue | undefined | Activity indicator color. Changed default activity indicator color. Only hex supported (iOS only) |
| base64Placeholder | string | | The base64 encoded placeholder image to show while the image is loading |
| cachePolicy | string | memory | The cache policy of the image |
| transitionDuration | number | 0.75 (iOS) 100 (Android) | The transition duration of the image |
| borderRadius | number | 0 | border radius of image |
| borderTopLeftRadius | number | 0 | top left border radius of image |
| borderTopRightRadius | number | 0 | top right border radius of image |
| borderBottomLeftRadius | number | 0 | bottom left border radius of image |
| borderBottomRightRadius | number | 0 | bottom right border radius of image |
| failureImage | string | | If the image fails to download this will be set (blurhash, thumbhash, base64) |
| progressiveLoadingEnabled | boolean | false | Progressively load images (iOS only) |
| onError | function | | The function to call when an error occurs. The error is passed as the first argument of the function |
| onSuccess | function | | The function to call when the image is successfully loaded |
| grayscale | number | 0 | Filter or transformation that converts the image into shades of gray (0-1). |
| colorMatrix | number[][] | | Color matrix that is applied to image |
| ignoreQueryParamsForCacheKey | boolean | false | Ignore URL query parameters in cache keys |
| allowHardware | boolean | true | Allow hardware rendering (Android only) |
| headers | Record<string, string> | undefined | Pass in headers |
| accessibilityLabel | string | undefined | accessibility label |
| accessible | boolean | undefined | is accessible |

The source prop of FasterImageView accepts an ImageOptions object.

Required Fields:

• url: The string URL of the image.

Common Optional Fields:

• resizeMode: 'fill' | 'contain' | 'cover' | 'center' | 'top' | 'bottom' (Note: iOS supports more positions like topLeft, bottomRight, etc.)
• cachePolicy: 'memory' | 'discWithCacheControl' | 'discNoCacheControl' | 'memoryAndDisc'. Defaults to 'memory'.
• transitionDuration: Duration of the transition animation in seconds (defaults to 0.75).
• blurhash / thumbhash / base64Placeholder: Used for progressive loading or placeholder display.
• failureImage: Image to show when loading fails (can be a URL, blurhash, thumbhash, or base64).
• contentPosition: Position of the image content within the view (e.g., 'top', 'bottom', 'topLeft').
• priority: (iOS only) 'veryLow' | 'low' | 'normal' | 'high' | 'veryHigh'.
• showActivityIndicator: (iOS only) Shows a loading indicator, overriding placeholders.