Intégration React#

Le package @snapkit-studio/react fournit une intégration transparente des capacités d'optimisation d'images de Snapkit dans vos applications React.

Installation#

Installez Snapkit pour votre projet React :

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

Démarrage Rapide#

Configuration de l'Environnement#

D'abord, configurez vos variables d'environnement :

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

Utilisation de Base#

La façon la plus simple d'utiliser Snapkit dans votre application React :

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

Avec SnapkitProvider (Recommandé)#

Pour les applications avec plusieurs images et une configuration centralisée :

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="Image hero"
      width={800}
      height={600}
    />
  );
}

Fonctionnalités Principales#

Optimisation Automatique du Format#

Snapkit sélectionne automatiquement le meilleur format d'image basé sur le support du navigateur :

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

Transformations Visuelles#

Appliquez divers effets visuels et transformations :

// Effet niveaux de gris
<Image
  src="/photo.jpg"
  transforms={{ grayscale: true }}
/>
 
// Effet de flou
<Image
  src="/background.jpg"
  transforms={{ blur: 20 }}
/>
 
// Miroir et rotation
<Image
  src="/icon.png"
  transforms={{
    flip: true,
    rotate: 90
  }}
/>

Extraction de Région#

Extrayez des régions spécifiques des images :

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

Optimisation de Performance#

Priority Loading#

Pour les images above-the-fold qui doivent se charger immédiatement :

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

Lazy Loading#

Pour les images below-the-fold afin d'améliorer le chargement initial de la page :

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

Images Responsives#

Mode Fill#

Pour les images qui doivent remplir leur conteneur :

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

Dimensionnement Responsif#

Avec génération de srcset pour différentes tailles d'écran :

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

Optimisation de la Taille du Bundle#

Import Optimisé (~9KB)#

Pour les applications où la taille du bundle est critique :

import { Image } from '@snapkit-studio/react/image';
 
// Utiliser sans provider - configurer via props
<Image
  src="/photo.jpg"
  baseUrl="https://your-cdn.snapkit.studio"
  organizationName="your-org"
  width={400}
  height={300}
/>

Bundle Complet (~22KB)#

Lors de l'utilisation du pattern provider pour une configuration centralisée :

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

Configuration Avancée#

Loader Personnalisé#

Créez un loader d'image personnalisé pour des exigences spécifiques :

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}
/>

Support TypeScript#

Support TypeScript complet avec transformations 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}
/>

Meilleures Pratiques#

Utiliser Provider pour Plusieurs Images : Quand votre application a beaucoup d'images, utilisez SnapkitProvider pour éviter une configuration répétitive.
Optimiser les Images Critiques : Utilisez priority={true} pour les images above-the-fold pour améliorer le LCP (Largest Contentful Paint).
Lazy Load les Images Below-Fold : Utilisez loading="lazy" pour les images non immédiatement visibles pour améliorer le chargement initial de la page.
Définir les Dimensions Appropriées : Toujours fournir width et height pour prévenir le layout shift (CLS).
Utiliser Auto Format : Laissez Snapkit automatiquement sélectionner le meilleur format avec transforms={{ format: 'auto' }}.

Guide de Migration#

Depuis les Balises IMG Natives#

// Avant
<img
  src="/image.jpg"
  alt="Description"
  width="400"
  height="300"
/>
 
// Après
<Image
  src="/image.jpg"
  alt="Description"
  width={400}
  height={300}
  transforms={{ format: 'auto' }}
/>

Depuis d'Autres Composants d'Image#

La plupart des composants d'image peuvent être remplacés directement avec des changements minimaux :

// Avant (autre bibliothèque)
<OptimizedImage
  source="/photo.jpg"
  width={500}
  height={400}
/>
 
// Après (Snapkit)
<Image
  src="/photo.jpg"
  width={500}
  height={400}
  transforms={{ format: 'auto' }}
/>

Dépannage#

Problèmes Communs#

Images ne se chargent pas : Assurez-vous que votre baseUrl et organizationName sont correctement configurés.
Erreurs TypeScript : Assurez-vous d'avoir la dernière version de @snapkit-studio/react installée.
Layout shift : Toujours fournir des attributs explicites width et height.
Images floues : Vérifiez que vous ne dimensionnez pas les images au-delà de leurs dimensions originales.

Support des Navigateurs#

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

Résumé des Fonctionnalités Principales#

Détection automatique de format (AVIF, WebP, JPEG)
Compatibilité avec le composant Next.js Image
Support TypeScript
Chargement d'images responsive
Optimisation basée sur DPR
Lazy loading
Ajustement de qualité conscient du réseau