React-Integration#

Das @snapkit-studio/react-Paket bietet nahtlose Integration von Snapkits Bildoptimierungsfunktionen in Ihre React-Anwendungen.

Installation#

Installieren Sie Snapkit für Ihr React-Projekt:

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

Schnellstart#

Umgebungskonfiguration#

Richten Sie zuerst Ihre Umgebungsvariablen ein:

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

Grundlegende Verwendung#

Der einfachste Weg, Snapkit in Ihrer React-Anwendung zu verwenden:

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

Mit SnapkitProvider (Empfohlen)#

Für Anwendungen mit mehreren Bildern und zentralisierter Konfiguration:

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

Hauptfunktionen#

Automatische Formaterkennung#

Snapkit erkennt automatisch und liefert das beste Format (AVIF, WebP, JPEG) basierend auf Browser-Unterstützung:

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

Netzwerk-bewusste Qualitätsanpassung#

Dynamische Qualitätsanpassung basierend auf Netzwerkbedingungen:

<Image
  src="/high-res.jpg"
  alt="Hochauflösendes Bild"
  width={1200}
  height={800}
  transforms={{ quality: 'auto' }}
/>

Visuelle Transformationen#

Verschiedene visuelle Effekte und Transformationen anwenden:

// Graustufen-Effekt
<Image
  src="/photo.jpg"
  transforms={{ grayscale: true }}
/>
 
// Unschärfe-Effekt
<Image
  src="/background.jpg"
  transforms={{ blur: 20 }}
/>
 
// Spiegeln und drehen
<Image
  src="/icon.png"
  transforms={{
    flip: true,
    rotate: 90
  }}
/>

Bereichsextraktion#

Spezifische Bereiche aus Bildern extrahieren:

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

Performance-Optimierung#

Priority Loading#

Für above-the-fold Bilder, die sofort laden sollten:

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

Lazy Loading#

Für below-the-fold Bilder zur Verbesserung des initialen Seitenladens:

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

Responsive Bilder#

Fill-Modus#

Für Bilder, die ihren Container füllen sollen:

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

Responsive Größenänderung#

Mit srcset-Generierung für verschiedene Bildschirmgrößen:

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

Bundle-Größen-Optimierung#

Optimierter Import (~9KB)#

Für Anwendungen, bei denen Bundle-Größe kritisch ist:

import { Image } from '@snapkit-studio/react/image';
 
// Ohne Provider verwenden - über Props konfigurieren
<Image
  src="/photo.jpg"
  baseUrl="https://your-cdn.snapkit.studio"
  organizationName="your-org"
  width={400}
  height={300}
/>

Vollständiges Bundle (~22KB)#

Bei Verwendung des Provider-Patterns für zentralisierte Konfiguration:

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

Erweiterte Konfiguration#

Benutzerdefinierter Loader#

Erstellen Sie einen benutzerdefinierten Bildlader für spezifische Anforderungen:

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

TypeScript-Unterstützung#

Vollständige TypeScript-Unterstützung mit typsicheren Transformationen:

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

Best Practices#

Provider für mehrere Bilder verwenden: Wenn Ihre Anwendung viele Bilder hat, verwenden Sie SnapkitProvider, um wiederholte Konfiguration zu vermeiden.
Kritische Bilder optimieren: Verwenden Sie priority={true} für above-the-fold Bilder, um LCP (Largest Contentful Paint) zu verbessern.
Below-Fold Bilder lazy laden: Verwenden Sie loading="lazy" für nicht sofort sichtbare Bilder, um das initiale Seitenladen zu verbessern.
Angemessene Dimensionen setzen: Stellen Sie immer Breite und Höhe bereit, um Layout-Shift (CLS) zu verhindern.
Auto-Format verwenden: Lassen Sie Snapkit automatisch das beste Format mit transforms={{ format: 'auto' }} auswählen.

Migrationsleitfaden#

Von nativen IMG-Tags#

// Vorher
<img
  src="/image.jpg"
  alt="Beschreibung"
  width="400"
  height="300"
/>
 
// Nachher
<Image
  src="/image.jpg"
  alt="Beschreibung"
  width={400}
  height={300}
  transforms={{ format: 'auto' }}
/>

Von anderen Bildkomponenten#

Die meisten Bildkomponenten können direkt mit minimalen Änderungen ersetzt werden:

// Vorher (andere Bibliothek)
<OptimizedImage
  source="/photo.jpg"
  width={500}
  height={400}
/>
 
// Nachher (Snapkit)
<Image
  src="/photo.jpg"
  width={500}
  height={400}
  transforms={{ format: 'auto' }}
/>

Fehlerbehebung#

Häufige Probleme#

Bilder laden nicht: Stellen Sie sicher, dass Ihre baseUrl und organizationName korrekt konfiguriert sind.
TypeScript-Fehler: Stellen Sie sicher, dass Sie die neueste Version von @snapkit-studio/react installiert haben.
Layout-Shift: Stellen Sie immer explizite Breiten- und Höhenattribute bereit.
Unscharfe Bilder: Überprüfen Sie, dass Sie Bilder nicht über ihre ursprünglichen Dimensionen hinaus skalieren.

Browser-Unterstützung#

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

Zusammenfassung der Hauptfunktionen#

Automatische Formaterkennung (AVIF, WebP, JPEG)
Next.js Image-Komponenten-Kompatibilität
TypeScript-Unterstützung
Responsive Bildladen
DPR-basierte Optimierung
Lazy Loading
Netzwerk-bewusste Qualitätsanpassung