expo-image

Almacenamiento en caché, placeholders, writeToCacheAsync y carga progresiva - el cookbook de expo-image para Expo SDK 57 feeds, galerías y miniaturas offline-first.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

npx expo install expo-image

import { Image } from "expo-image";
 
const BLURHASH =
  "L6PZfSi_.AyE_3t7t7R**0o#DgR4";
 
export function FeedThumb({ uri }: { uri: string }) {
  return (
    <Image
      source={{ uri }}
      placeholder={{ blurhash: BLURHASH }}
      placeholderContentFit="cover"
      contentFit="cover"
      transition={300}
      cachePolicy="memory-disk"
      style={{ width: "100%", aspectRatio: 1, borderRadius: 8 }}
    />
  );
}

// Inicializa el caché después de que expo-image-picker devuelva un URI local
import { Image } from "expo-image";
 
export async function cachePickedPhoto(localUri: string, assetId: string) {
  const cacheKey = `upload:${assetId}`;
  await Image.writeToCacheAsync(localUri, cacheKey);
  return cacheKey;
}

Cuándo usarlo:

• Grillas de avatares, catálogos de productos y feeds sociales con URLs remotas.
• Pantallas que necesitan placeholders de BlurHash o ThumbHash desde tu API.
• Filas de FlashList o FlatList donde la imagen de la fila anterior parpadea durante el reciclaje.
• Redes offline o intermitentes donde el caché de disco debe sobrevivir a los reinicios de la app.

Cuándo evitarlo:

• Solo iconos estáticos require() pequeños - RN Image funciona bien.
• Páginas PDF o previsualizaciones de documentos - usa expo-document-picker y un visor de documentos.
• Galerías de pinch-zoom a pantalla completa con gestos complejos - considera una biblioteca de galería dedicada encima de expo-image.

Ejemplo funcional

Fila de feed con bytes progresivos, inicialización de caché desde captura y reciclaje seguro para listas.

npx expo install expo-image expo-image-picker

// src/media/FeedImageRow.tsx
import { useState } from "react";
import { Image, ImageLoadEventData } from "expo-image";
import { StyleSheet, Text, View } from "react-native";
 
type Props = {
  id: string;
  uri: string;
  blurhash: string;
  width: number;
};
 
export function FeedImageRow({ id, uri, blurhash, width }: Props) {
  const [progress, setProgress] = useState(0);
 
  return (
    <View style={[styles.card, { width }]}>
      <Image
        source={{ uri, cacheKey: `feed:${id}` }}
        recyclingKey={id}
        placeholder={{ blurhash }}
        placeholderContentFit="cover"
        contentFit="cover"
        cachePolicy="memory-disk"
        priority="normal"
        transition={250}
        onProgress={({ loaded, total }) => {
          if (total > 0) setProgress(loaded / total);
        }}
        onLoad={() => setProgress(1)}
        style={styles.image}
      />
      {progress > 0 && progress < 1 ? (
        <Text style={styles.progress}>{Math.round(progress * 100)}%</Text>
      ) : null}
    </View>
  );
}
 
const styles = StyleSheet.create({
  card: { aspectRatio: 4 / 3, borderRadius: 10, overflow: "hidden", backgroundColor: "#e5e7eb" },
  image: { flex: 1 },
  progress: {
    position: "absolute",
    bottom: 8,
    right: 8,
    fontSize: 11,
    color: "#fff",
    backgroundColor: "rgba(0,0,0,0.45)",
    paddingHorizontal: 6,
    paddingVertical: 2,
    borderRadius: 4,
  },
});

// src/media/prefetchFeed.ts
import { Image } from "expo-image";
 
export async function prefetchNextPage(urls: string[]) {
  return Image.prefetch(urls, { cachePolicy: "memory-disk" });
}

Lo que esto demuestra:

• recyclingKey={id} limpia la celda antes de que se cargue la nueva fuente - crítico en listas virtualizadas.
• onProgress impulsa una etiqueta de porcentaje ligera sin código de descarga personalizado.
• cacheKey en source se empareja con writeToCacheAsync para capturas que ya posees.
• Image.prefetch calienta el disco + memoria antes de que el usuario abra una pantalla de detalles.

Análisis profundo

Políticas de caché

<Image source={{ uri: signedUrl }} cachePolicy="none" />

Las URLs firmadas con TTL corto deben usar none o una clave de caché que rote cuando la firma rota.

Placeholders: BlurHash, ThumbHash y local

<Image
  source="https://cdn.example.com/hero.webp"
  placeholder={{ blurhash: post.blurhash }}
  placeholderContentFit="cover"
  contentFit="cover"
  transition={400}
/>

• Empareja placeholderContentFit con contentFit - el predeterminado scale-down en placeholders causa parpadeo.
• ThumbHash es más pequeño que BlurHash para algunos assets - el backend puede emitir cualquiera.
• Para previsualizaciones locales de baja resolución, pasa un number de require() como placeholder mientras se carga la URL HD.

Flujo de writeToCacheAsync

import { Image } from "expo-image";
import * as FileSystem from "expo-file-system";
 
export async function cacheDownloadedFile(remoteUrl: string, stableId: string) {
  const tempUri = `${FileSystem.cacheDirectory}dl-${stableId}.jpg`;
  await FileSystem.downloadAsync(remoteUrl, tempUri);
  const cacheKey = `asset:${stableId}`;
  await Image.writeToCacheAsync(tempUri, cacheKey);
  return { cacheKey, displayUri: tempUri };
}

<Image source={{ uri: displayUri, cacheKey }} contentFit="cover" style={{ flex: 1 }} />

• Pasa un URI de archivo local o ImageRef de takePictureAsync({ pictureRef: true }).
• GIF/WebP animado de ImageRef se aplana a un fotograma - pasa el URI del archivo para animación sin pérdida.
• Renderizados posteriores con la misma cacheKey omiten la red completamente.

Carga progresiva en UX de producto

function onProgress(event: { loaded: number; total: number }) {
  const ratio = event.total > 0 ? event.loaded / event.total : 0;
  // Impulsa una barra determinada o ancho de skeleton - mantén el trabajo O(1)
}

• onLoadStart / onLoad / onDisplay marcan las transiciones skeleton - cargado - pintado.
• No almacenes cada evento de progreso en estado global - actualiza solo el estado local de la fila.
• Combina con priority="high" para imágenes hero por encima del pliegue.

Higiene de listas

<Image
  recyclingKey={item.id}
  source={{ uri: item.thumbUrl, cacheKey: `thumb:${item.id}` }}
  allowDownscaling
  style={{ width: 72, height: 72 }}
/>

• allowDownscaling (predeterminado true) decodifica cerca del tamaño de vista - déjalo activado a menos que necesites máxima calidad en una caja pequeña.
• enforceEarlyResizing en iOS reduce el pico de memoria para assets CDN sobredimensionados.
• Empareja con reglas memo de List Performance Tuning.

Mantenimiento de caché

await Image.clearMemoryCache();
await Image.clearDiskCache();

Llamar desde una acción Settings - Clear cache o cuando el usuario cierre sesión. La limpieza de disco es asincrónica y no debe ejecutarse en cada enfoque de pantalla.

Errores comunes

• Falta recyclingKey en FlashList - el avatar del usuario anterior parpadea. Solución: recyclingKey={item.id}.
• Desajuste de ajuste de placeholder - el shimmer salta cuando se carga HD. Solución: placeholderContentFit="cover" coincidiendo con contentFit.
• Almacenamiento en caché de URLs firmadas que expiran - imagen obsoleta o bucles 403. Solución: cachePolicy="none" o rota cacheKey con firma.
• Migración de RN Image - resizeMode se asigna a contentFit, no 1:1 para todos los valores. Solución: lee la tabla de props al portar.
• writeToCacheAsync en URL remota - API espera archivo local. Solución: descarga al directorio de caché primero.
• WebP animado enorme en lista de avatares - decodifica cada fotograma. Solución: sirve URL de miniatura estática; carga la animación solo en detalles.

Alternativas

Preguntas frecuentes

npx expo install expo-image

Relacionado

• Media Basics - elección de módulo de captura versus visualización
• expo-camera & expo-image-picker - flujos de captura y biblioteca
• List Performance Tuning - memo y reciclaje
• expo-video - caché de reproducción de video
• Media Best Practices - lista de verificación de compresión y memoria

Versiones de Stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).