Snapkit Logo

Next.js-Integration#

Das @snapkit-studio/nextjs-Paket bietet tiefe Integration mit Next.js und bietet vollständige Kompatibilität mit Next.js Image-Komponenten-APIs, während es Snapkits mächtige Transformationsfunktionen hinzufügt.

Installation#

Installieren Sie Snapkit für Ihr Next.js-Projekt:

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

Schnellstart#

Umgebungskonfiguration#

Richten Sie zuerst Ihre Umgebungsvariablen in .env.local ein:

NEXT_PUBLIC_SNAPKIT_ORGANIZATION_NAME=your-organization-name
NEXT_PUBLIC_SNAPKIT_DEFAULT_QUALITY=85
NEXT_PUBLIC_SNAPKIT_DEFAULT_OPTIMIZE_FORMAT=auto

App Router Setup#

Konfigurieren Sie Snapkit in Ihrem Root-Layout:

// app/layout.tsx
import { SnapkitProvider } from '@snapkit-studio/nextjs';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="de">
      <body>
        <SnapkitProvider
          baseUrl="https://snapkit-cdn.snapkit.studio"
          organizationName="your-org"
          defaultQuality={85}
          defaultFormat="auto"
        >
          {children}
        </SnapkitProvider>
      </body>
    </html>
  );
}

Pages Router Setup#

Für Pages Router, fügen Sie den Provider zu _app.tsx hinzu:

// pages/_app.tsx
import { SnapkitProvider } from '@snapkit-studio/nextjs';
import type { AppProps } from 'next/app';
 
export default function App({ Component, pageProps }: AppProps) {
  return (
    <SnapkitProvider
      baseUrl="https://snapkit-cdn.snapkit.studio"
      organizationName="your-org"
      defaultQuality={85}
      defaultFormat="auto"
    >
      <Component {...pageProps} />
    </SnapkitProvider>
  );
}

Hauptfunktionen#

Drop-in Ersatz#

Ersetzen Sie Next.js Image-Komponente ohne Konfigurationsänderungen:

// Vorher
import Image from 'next/image';
 
// Nachher
import { Image } from '@snapkit-studio/nextjs';
 
// Verwendung bleibt gleich
<Image
  src="/hero.jpg"
  alt="Hero-Bild"
  width={800}
  height={600}
  priority
/>

Grundlegendes Verwendungsbeispiel#

Einfache Verwendung mit automatischer Optimierung:

import { Image } from '@snapkit-studio/nextjs';
 
<Image
  src="/photo.jpg"
  width={800}
  height={600}
  alt="Foto"
  priority
  transforms={{
    format: 'auto',
    quality: 85
  }}
/>

Erweiterte Transformationen#

Fügen Sie mächtige Transformationen über Next.js-Funktionen hinaus hinzu:

import { Image } from '@snapkit-studio/nextjs';
 
<Image
  src="/product.jpg"
  alt="Produktbild"
  width={400}
  height={300}
  transforms={{
    format: 'auto',
    quality: 90,
    sharpen: true,
    blur: 0,
    grayscale: false
  }}
  className="rounded-lg shadow-md"
/>

Automatische Optimierung#

Format-Auswahl#

Liefern Sie automatisch moderne Formate basierend auf Browser-Unterstützung:

<Image
  src="/photo.jpg"
  width={600}
  height={400}
  transforms={{
    format: 'auto' // Liefert WebP, AVIF oder ursprüngliches Format
  }}
/>

Netzwerk-bewusste Qualitätsanpassung#

Dynamische Qualitätsoptimierung basierend auf Netzwerkbedingungen:

<Image
  src="/high-res.jpg"
  width={1200}
  height={800}
  transforms={{
    quality: 'auto' // Passt basierend auf Verbindungsgeschwindigkeit an
  }}
/>

Next.js-spezifische Funktionen#

Bildoptimierung#

Statische Imports#

Vollständige Unterstützung für statische Bildimports mit Build-Time-Optimierung:

import heroImage from '@/public/hero.jpg';
 
<Image
  src={heroImage}
  alt="Hero"
  placeholder="blur"
  priority
  transforms={{ format: 'auto' }}
/>

Dynamische Imports#

Für dynamisch geladene Bilder:

<Image
  src={`/products/${productId}.jpg`}
  width={500}
  height={500}
  transforms={{
    format: 'auto',
    fit: 'cover'
  }}
/>

Responsive Bilder#

Container füllen#

Für responsive Container-basierte Layouts:

<div className="relative aspect-video">
  <Image
    src="/banner.jpg"
    alt="Banner"
    fill
    sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
    className="object-cover"
    transforms={{ format: 'auto' }}
  />
</div>

Art Direction#

Verschiedene Bilder für verschiedene Breakpoints:

<picture>
  <source
    media="(max-width: 768px)"
    srcSet="/mobile-hero.jpg"
  />
  <Image
    src="/desktop-hero.jpg"
    width={1920}
    height={1080}
    alt="Responsive Hero"
    transforms={{ format: 'auto' }}
  />
</picture>

Performance-Funktionen#

Priority Loading#

Für LCP-Optimierung:

<Image
  src="/above-fold.jpg"
  width={1200}
  height={600}
  priority
  transforms={{
    format: 'auto',
    quality: 90
  }}
/>

Lazy Loading mit Platzhalter#

Sanfte Ladeerfahrung:

<Image
  src="/gallery-image.jpg"
  width={400}
  height={300}
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,..."
  loading="lazy"
/>

Konfiguration#

next.config.js Setup#

Konfigurieren Sie Snapkit als Ihre Bildoptimierungslösung:

// next.config.js
module.exports = {
  images: {
    domains: ['snapkit-cdn.snapkit.studio'],
    loader: 'custom',
    loaderFile: './snapkit-loader.js',
  },
};

Benutzerdefinierter Loader#

Erstellen Sie einen benutzerdefinierten Loader für erweiterte Anwendungsfälle:

// snapkit-loader.js
export default function snapkitLoader({ src, width, quality }) {
  const url = new URL(`https://your-org-cdn.snapkit.studio/${src}`);
 
  const params = {
    w: width,
    q: quality || 75,
    auto: 'format',
  };
 
  Object.keys(params).forEach(key =>
    url.searchParams.set(key, params[key])
  );
 
  return url.href;
}

App Router Funktionen#

Server-Komponenten#

Vollständige Unterstützung für React Server Components:

// app/gallery/page.tsx
import { Image } from '@snapkit-studio/nextjs';
 
export default async function Gallery() {
  const images = await fetchImages();
 
  return (
    <div className="grid grid-cols-3 gap-4">
      {images.map((img) => (
        <Image
          key={img.id}
          src={img.url}
          width={400}
          height={300}
          alt={img.alt}
          transforms={{ format: 'auto' }}
        />
      ))}
    </div>
  );
}

Client-Komponenten#

Nahtlose Integration mit Client-seitigen Funktionen:

'use client';
 
import { useState } from 'react';
import { Image } from '@snapkit-studio/nextjs';
 
export default function InteractiveGallery() {
  const [selectedImage, setSelectedImage] = useState(0);
 
  return (
    <Image
      src={images[selectedImage]}
      width={800}
      height={600}
      transforms={{
        format: 'auto',
        quality: 90
      }}
    />
  );
}

Erweiterte Verwendung#

Metadaten-Generierung#

Für SEO und Social Sharing:

// app/products/[id]/page.tsx
import { Metadata } from 'next';
 
export async function generateMetadata({ params }): Promise<Metadata> {
  const product = await getProduct(params.id);
 
  return {
    openGraph: {
      images: [{
        url: `https://your-cdn.snapkit.studio/${product.image}?w=1200&h=630&fit=cover`,
        width: 1200,
        height: 630,
      }],
    },
  };
}

ISR und SSG#

Vollständige Unterstützung für Incremental Static Regeneration:

// app/blog/[slug]/page.tsx
export const revalidate = 3600; // Jede Stunde revalidieren
 
export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);
 
  return (
    <Image
      src={post.featuredImage}
      width={1200}
      height={600}
      alt={post.title}
      priority
      transforms={{ format: 'auto' }}
    />
  );
}

Edge Runtime#

Optimiert für Edge Runtime:

export const runtime = 'edge';
 
export default function EdgeOptimizedPage() {
  return (
    <Image
      src="/edge-optimized.jpg"
      width={600}
      height={400}
      transforms={{
        format: 'auto',
        quality: 85
      }}
    />
  );
}

Migrationsleitfaden#

Von next/image#

Minimale Änderungen erforderlich:

// Schritt 1: Import aktualisieren
- import Image from 'next/image';
+ import { Image } from '@snapkit-studio/nextjs';
 
// Schritt 2: Transforms hinzufügen (optional)
<Image
  src="/photo.jpg"
  width={500}
  height={300}
+ transforms={{ format: 'auto' }}
/>

Von Legacy Next.js#

Für Next.js 12 und früher:

// Vorher (Next.js 12)
<Image
  src="/photo.jpg"
  width={500}
  height={300}
  layout="responsive"
/>
 
// Nachher (mit Snapkit)
<Image
  src="/photo.jpg"
  width={500}
  height={300}
  sizes="100vw"
  style={{
    width: '100%',
    height: 'auto',
  }}
  transforms={{ format: 'auto' }}
/>

Performance-Optimierung#

Build-Time-Optimierung#

Optimierte Bilder während des Builds generieren:

// next.config.js
module.exports = {
  experimental: {
    optimizeImages: true,
  },
};

Runtime-Optimierung#

Dynamische Optimierung basierend auf Benutzerkontext:

<Image
  src="/dynamic.jpg"
  width={800}
  height={600}
  transforms={{
    format: 'auto',
    quality: typeof window !== 'undefined'
      ? navigator.connection?.saveData ? 60 : 85
      : 85,
  }}
/>

Best Practices#

  1. App Router verwenden: Nutzen Sie React Server Components für bessere Performance.

  2. Caching aktivieren: Konfigurieren Sie ordnungsgemäße Cache-Header für optimierte Bilder.

  3. Above-the-fold optimieren: Verwenden Sie priority-Prop für kritische Bilder.

  4. Responsive Bilder: Stellen Sie immer sizes-Prop für responsive Layouts bereit.

  5. Format Auto: Lassen Sie Snapkit automatisch das beste Format wählen.

Fehlerbehebung#

Häufige Probleme#

  1. Hydration Mismatch: Stellen Sie konsistentes Rendering zwischen Server und Client sicher.

  2. CORS-Probleme: Konfigurieren Sie Domains in next.config.js.

  3. Build-Fehler: Überprüfen Sie, dass alle statischen Imports gültig sind.

  4. Performance-Probleme: Verifizieren Sie die Caching-Konfiguration.

Zusammenfassung der Hauptfunktionen#

  • Nahtlose Next.js Image-Komponenten-Integration
  • Automatische Bildtransformation
  • Dynamische DPR-basierte srcset-Generierung
  • Intelligente Formatauswahl (WebP, AVIF)
  • Server- und Client-Komponenten-Unterstützung
  • TypeScript-Definitionen
  • 90%+ Testabdeckung

Ressourcen#