Viewer für Next.js
@transloadit/viewer rendert responsive Bilder, deren Bytes direkt vom Smart CDN kommen,
ohne die Next.js-Bildoptimierung zu durchlaufen. Nutzen Sie Originale in Transloadit Storage oder
behalten Sie Ihre bestehende HTTP/S3-Quelle bei. Für die Integration müssen Sie Ihre Dateien nicht
migrieren.
Viewer ist eine Alpha-Version. Diese Anleitung verwendet
@transloadit/viewer@0.1.0, Next.js 16.3.3+ mit dem App Router, React 19 und die Node.js-Laufzeit. Fixieren Sie die getestete Viewer-Version. Die KomponenteImageist kein direkt austauschbarerloaderFilefür das standardmäßigenext/image.
Mit öffentlichen Storage-Bildern beginnen
Nutzen Sie diesen Ansatz für öffentliche Website-Bilder, die Sie zusammen mit Ihrem Code verwalten. Für von Nutzern hochgeladene oder private Medien verwenden Sie stattdessen die Anwendungsintegration. Storage ist in der privaten Vorschauphase; bitten Sie uns zunächst um die Freischaltung für Ihren Workspace.
Installieren Sie die veröffentlichten Pakete in Ihrem bestehenden Next.js-Projekt. Diese Beispiele verwenden npm. Behalten Sie den Paketmanager und die Lockdatei Ihres Projekts bei, wenn es bereits Yarn oder pnpm nutzt.
npm install --save-exact @transloadit/viewer@0.1.0
npm install --save-dev --save-exact @transloadit/node@6.9.0
Legen Sie ein JPEG ohne sensible Inhalte unter ./hero.jpg ab und führen Sie dann
Folgendes aus:
npx @transloadit/node@6.9.0 auth login
npx @transloadit/node@6.9.0 storage store ./hero.jpg website/hero.jpg --public --hashed
Bestätigen Sie den vorgesehenen Workspace im Browser. Falls Sie kein Konto haben, können Sie sich
dort registrieren. --public veröffentlicht das gesamte Zielverzeichnis
rekursiv, einschließlich bestehender Dateien und künftiger Uploads. Verwenden Sie ein eigenes
Verzeichnis, das nur Medien enthält, die öffentlich sein sollen.
storage store allein veröffentlicht kein Verzeichnis.
Binden Sie Ihre bestehende Konfiguration für next.config.ts wie folgt ein:
import type { NextConfig } from 'next'
import { withTransloaditImages } from '@transloadit/viewer/next/config'
const nextConfig: NextConfig = {}
export default withTransloaditImages(nextConfig)
Verwenden Sie in app/page.tsx (oder src/app/page.tsx) exakt den Pfad,
den der Upload-Befehl ausgibt. Der folgende Hash ist ein Beispiel und keine Datei, die bereits in
Ihrem Workspace existiert:
import { Image } from '@transloadit/viewer/next'
export default function Page() {
return (
<Image
storage
src="website/hero.fce9d56a.jpg"
alt="A canal house beside the water"
width={960}
preload
/>
)
}
Führen Sie npm run dev aus und öffnen Sie die Seite. Committen Sie die generierten
Dateien transloadit.images.json und transloadit-images.d.ts mit Ihrer App, aber keine
CLI-Zugangsdaten. Das Plugin bündelt den Katalog. Die öffentliche Auslieferung benötigt daher weder
Signatur-Secrets der Anwendung noch eine Metadatenabfrage zur Laufzeit. Optionales Grundgerüst für
eine bestehende App finden Sie in der gepflegten
Anleitung zu image init.
Responsive Größen und Ladeverhalten
width={960} begrenzt die responsive Anzeigebreite; der Browser wählt aus den
generierten Varianten. Verwenden Sie preload für das wichtige Bild im sofort
sichtbaren Seitenbereich, nicht für jedes Bild einer Galerie. Andere Bilder werden standardmäßig
verzögert geladen. Setzen Sie sizes, wenn Ihr Layout eine genauere
Größenangabe benötigt.
Für einen unscharfen Platzhalter ergänzen Sie den Upload-Befehl um --placeholder blur
und Image um placeholder="blur".
Die Extraktion ist optionale serverseitige Arbeit und verursacht bei Erfolg eine zusätzliche
Metadatennutzung in Höhe von 20 % der Dateibytes. Wiederholen Sie einen bereits abgeschlossenen
Upload nicht nur, um einen Platzhalter hinzuzufügen. Details zu Layouts, Bildausschnitten und dem
Platzhalterverhalten finden Sie in der
Referenz zu responsiven Bildern.
Bestehende HTTP- oder S3-Quelle beibehalten
Dieser Ansatz benötigt weder einen Upload zu Storage noch einen Katalog. Installieren Sie Viewer wie oben und erstellen Sie dann ein kompatibles, eingeschränktes Template mit dem gepflegten HTTP- oder S3-Beispiel. Legen Sie die zulässige Quelle oder den Bucket samt Präfix fest, verlangen Sie Signaturen und deaktivieren Sie Step-Überschreibungen. Lassen Sie nicht zu, dass Browsereingaben beliebige Import-URLs oder Transformationen festlegen.
Konfigurieren Sie für diesen Workspace einen separaten Anwendungs-Auth Key mit
smart_cdn:sign und setzen Sie TRANSLOADIT_SMART_CDN_KEY sowie
TRANSLOADIT_SMART_CDN_SECRET in Ihrer ausschließlich serverseitigen Umgebung. Stellen Sie den
CLI-Anmeldeschlüssel nicht bereit: Beim Abmelden wird er widerrufen. Bewahren Sie S3-Zugangsdaten in
den eingeschränkten Zugangsdaten des Templates auf, niemals in JSX oder Browsercode.
Rendern Sie in einer Server Component und übergeben Sie die tatsächlichen Originalabmessungen aus vertrauenswürdigen Metadaten:
import { Image } from '@transloadit/viewer/next'
export default function Page() {
return (
<Image
workspace="my-shop"
template="products"
src="chairs/oak.jpg"
alt="An oak chair"
width={1200}
height={800}
/>
)
}
Ersetzen Sie Workspace, Template, relativen Pfad und Abmessungen durch Ihre eigenen Werte. Dieser
Modus benötigt withTransloaditImages nur, wenn Sie dessen Konfigurationsvorgaben nutzen
möchten. Die signierte direkte Auslieferung erfordert Arbeit zum Anfragezeitpunkt. Autorisieren Sie
bei privaten Dateien den Zugriff in der aufrufenden Server Component oder nutzen Sie die Route zur
Autorisierung pro Anfrage aus der Referenz.
Von Nutzern hochgeladene und private Medien
Ein committeter Katalog eignet sich für Website-Dateien, nicht für eine laufend aktualisierte Nutzergalerie. Für Uppy-Uploads, private Bilder und Videos verwenden Sie die React-Anleitung für Belege und autorisierte Auslieferung. Speichern Sie kanonische Belege zusammen mit ihrem Eigentümer und prüfen Sie vor der Medienauslieferung die aktuellen Zugriffsrechte für jede Datei. Die Convex-Integration und die interaktive Hochzeitsdemo zeigen, wie die Anwendung Mitgliedschaften verwaltet und dabei die wiederverwendbaren Komponenten für Upload und Auslieferung nutzt.
Andere Frameworks
Viewer bietet ein frameworkneutrales Bildmodell und serverseitige Handler mit separaten Adaptern für React und Next.js. Das obige Next.js-Konfigurationsplugin ist nur für Next.js-Apps gedacht. Für reines JavaScript oder ein anderes Framework beginnen Sie mit der frameworkneutralen Anleitung; sie benötigt weder React noch Next.js. Ihre Anwendung bleibt für ihre Benutzeroberfläche, ihr Routing und ihre Zugriffsregeln verantwortlich.
Integration überprüfen
- Prüfen Sie in den Entwicklertools des Browsers, ob Bildanfragen das Smart CDN Ihres Workspaces
erreichen und nicht über
/_next/imagelaufen. Ändern Sie die Viewport-Größe und prüfen Sie die angeforderte Bildgröße. - Vergleichen Sie eine Anfrage ohne gefüllten Cache mit einer wiederholten Anfrage. Die erste Transformation kann länger dauern. Prüfen Sie die tatsächlichen Antwortheader, statt anzunehmen, dass jede Anfrage aus dem Cache bedient wird.
- Prüfen Sie in einem schmalen Viewport, ob Alt-Texte aussagekräftig sind, das Layout stabil bleibt und Platzhalter wie erwartet funktionieren.
- Testen Sie bei privater Auslieferung sowohl einen unberechtigten als auch einen berechtigten Nutzer. Signierte URLs bleiben bis zum Ablauf nutzbar; bereits heruntergeladene Bytes lassen sich damit nicht zurückrufen.
Wenn ein Bild nicht geladen wird, nutzen Sie die Entwicklungsdiagnose von Viewer und die Anleitung zur Fehlerbehebung. Falls der Katalog verloren geht, stellen Sie die Belege wieder her, statt erneut hochzuladen. Vergleichen Sie die Preise anhand Ihrer eigenen Transformations-, Cache- und Auslieferungslast. Allein das Umgehen des Next-Optimierers belegt noch keine Kostenersparnis.