Integración React#

El paquete @snapkit-studio/react proporciona una integración perfecta de las capacidades de optimización de imágenes de Snapkit en tus aplicaciones React.

Instalación#

Instala Snapkit para tu proyecto React:

npm install @snapkit-studio/react
# o
yarn add @snapkit-studio/react
# o
pnpm add @snapkit-studio/react

Inicio Rápido#

Configuración del Entorno#

Primero, configura tus variables de entorno:

VITE_SNAPKIT_ORGANIZATION_NAME=your-organization-name
VITE_SNAPKIT_DEFAULT_QUALITY=85
VITE_SNAPKIT_DEFAULT_OPTIMIZE_FORMAT=auto

Uso Básico#

La forma más simple de usar Snapkit en tu aplicación React:

import { Image } from '@snapkit-studio/react';
 
function MyComponent() {
  return (
    <Image
      src="/project/hero.jpg"
      alt="Imagen Hero"
      width={800}
      height={600}
      priority
      transforms={{ format: 'auto' }}
    />
  );
}

Con SnapkitProvider (Recomendado)#

Para aplicaciones con múltiples imágenes y configuración centralizada:

import { SnapkitProvider, Image } from '@snapkit-studio/react';
 
function App() {
  return (
    <SnapkitProvider
      baseUrl="https://snapkit-cdn.snapkit.studio"
      organizationName="your-org"
      defaultQuality={85}
      defaultFormat="auto"
    >
      <YourApplication />
    </SnapkitProvider>
  );
}
 
function YourApplication() {
  return (
    <Image
      src="/hero.jpg"
      alt="Imagen hero"
      width={800}
      height={600}
    />
  );
}

Características Principales#

Detección Automática de Formato#

Snapkit detecta automáticamente y sirve el mejor formato (AVIF, WebP, JPEG) basado en el soporte del navegador:

<Image
  src="/product.jpg"
  alt="Producto"
  width={400}
  height={300}
  transforms={{ format: 'auto' }}
/>

Ajuste de Calidad Consciente de Red#

Ajuste dinámico de calidad basado en condiciones de red:

<Image
  src="/high-res.jpg"
  alt="Imagen de alta resolución"
  width={1200}
  height={800}
  transforms={{ quality: 'auto' }}
/>

Transformaciones Visuales#

Aplica varios efectos visuales y transformaciones:

// Efecto escala de grises
<Image
  src="/photo.jpg"
  transforms={{ grayscale: true }}
/>
 
// Efecto de desenfoque
<Image
  src="/background.jpg"
  transforms={{ blur: 20 }}
/>
 
// Voltear y rotar
<Image
  src="/icon.png"
  transforms={{
    flip: true,
    rotate: 90
  }}
/>

Extracción de Región#

Extrae regiones específicas de las imágenes:

<Image
  src="/large-image.jpg"
  transforms={{
    extract: {
      x: 100,
      y: 100,
      width: 400,
      height: 300
    }
  }}
/>

Optimización de Rendimiento#

Priority Loading#

Para imágenes above-the-fold que deben cargar inmediatamente:

<Image
  src="/hero-banner.jpg"
  priority={true}
  width={1200}
  height={600}
/>

Lazy Loading#

Para imágenes below-the-fold para mejorar la carga inicial de la página:

<Image
  src="/footer-image.jpg"
  loading="lazy"
  width={600}
  height={400}
/>

Imágenes Responsivas#

Modo Fill#

Para imágenes que deben llenar su contenedor:

<div className="relative w-full h-64 rounded-lg overflow-hidden">
  <Image
    src="/background.jpg"
    fill={true}
    className="object-cover"
    alt="Fondo"
  />
</div>

Dimensionado Responsivo#

Con generación de srcset para diferentes tamaños de pantalla:

<Image
  src="/responsive.jpg"
  width={800}
  height={600}
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
  transforms={{ format: 'auto' }}
/>

Optimización del Tamaño del Bundle#

Import Optimizado (~9KB)#

Para aplicaciones donde el tamaño del bundle es crítico:

import { Image } from '@snapkit-studio/react/image';
 
// Usar sin provider - configurar vía props
<Image
  src="/photo.jpg"
  baseUrl="https://your-cdn.snapkit.studio"
  organizationName="your-org"
  width={400}
  height={300}
/>

Bundle Completo (~22KB)#

Al usar el patrón provider para configuración centralizada:

import { Image, SnapkitProvider } from '@snapkit-studio/react';

Configuración Avanzada#

Loader Personalizado#

Crea un loader de imagen personalizado para requisitos específicos:

const customLoader = ({ src, width, quality }) => {
  const params = new URLSearchParams({
    w: width.toString(),
    q: (quality || 75).toString(),
  });
 
  return `https://your-cdn.snapkit.studio/${src}?${params}`;
};
 
<Image
  loader={customLoader}
  src="image.jpg"
  width={400}
  height={300}
/>

Soporte TypeScript#

Soporte completo de TypeScript con transformaciones type-safe:

import { Image, type ImageTransforms } from '@snapkit-studio/react';
 
const transforms: ImageTransforms = {
  format: 'webp',
  quality: 90,
  blur: 0,
  grayscale: false,
};
 
<Image
  src="/typed-image.jpg"
  transforms={transforms}
  width={600}
  height={400}
/>

Mejores Prácticas#

Usar Provider para Múltiples Imágenes: Cuando tu aplicación tiene muchas imágenes, usa SnapkitProvider para evitar configuración repetitiva.
Optimizar Imágenes Críticas: Usa priority={true} para imágenes above-the-fold para mejorar el LCP (Largest Contentful Paint).
Lazy Load Imágenes Below-Fold: Usa loading="lazy" para imágenes no inmediatamente visibles para mejorar la carga inicial de la página.
Establecer Dimensiones Apropiadas: Siempre proporciona width y height para prevenir layout shift (CLS).
Usar Auto Format: Deja que Snapkit seleccione automáticamente el mejor formato con transforms={{ format: 'auto' }}.

Guía de Migración#

Desde Etiquetas IMG Nativas#

// Antes
<img
  src="/image.jpg"
  alt="Descripción"
  width="400"
  height="300"
/>
 
// Después
<Image
  src="/image.jpg"
  alt="Descripción"
  width={400}
  height={300}
  transforms={{ format: 'auto' }}
/>

Desde Otros Componentes de Imagen#

La mayoría de los componentes de imagen pueden ser reemplazados directamente con cambios mínimos:

// Antes (otra biblioteca)
<OptimizedImage
  source="/photo.jpg"
  width={500}
  height={400}
/>
 
// Después (Snapkit)
<Image
  src="/photo.jpg"
  width={500}
  height={400}
  transforms={{ format: 'auto' }}
/>

Solución de Problemas#

Problemas Comunes#

Las imágenes no cargan: Asegúrate de que tu baseUrl y organizationName estén configurados correctamente.
Errores de TypeScript: Asegúrate de tener la última versión de @snapkit-studio/react instalada.
Layout shift: Siempre proporciona atributos explícitos de width y height.
Imágenes borrosas: Verifica que no estés escalando imágenes más allá de sus dimensiones originales.

Soporte de Navegadores#

AVIF: Chrome 85+, Firefox 93+, Safari 16+
WebP: Chrome 23+, Firefox 65+, Safari 14+
Lazy Loading: Chrome 76+, Firefox 75+, Safari 15.4+

Resumen de Características Principales#

Detección automática de formato (AVIF, WebP, JPEG)
Compatibilidad con componente Next.js Image
Soporte TypeScript
Carga de imágenes responsiva
Optimización basada en DPR
Lazy loading
Ajuste de calidad consciente de red