Viewer pour Next.js
@transloadit/viewer affiche des images adaptatives dont les octets proviennent directement
du Smart CDN, sans passer par l’optimisation d’images de Next.js. Utilisez des originaux dans
Transloadit Storage ou conservez votre origine HTTP/S3 existante. Vous n’avez pas besoin de migrer
vos fichiers pour utiliser cette intégration.
Viewer est en version alpha. Ce guide utilise
@transloadit/viewer@0.1.0, Next.js 16.3.3+ avec l’App Router, React 19 et l’environnement d’exécution Node.js. Figez la version de Viewer que vous testez. Son composantImagene remplace pas directementloaderFilepour le composant standardnext/image.
Commencer avec des images publiques dans Storage
Utilisez cette approche pour les images publiques de votre site gérées avec votre code. Pour les médias privés ou téléversés par les utilisateurs, utilisez plutôt l’intégration à l’application. Storage est en préversion privée ; demandez-nous de l’activer d’abord pour votre Workspace.
Dans votre projet Next.js existant, installez les paquets publiés. Ces exemples utilisent npm ; conservez le gestionnaire de paquets et le fichier de verrouillage de votre projet s’il utilise déjà Yarn ou pnpm.
npm install --save-exact @transloadit/viewer@0.1.0
npm install --save-dev --save-exact @transloadit/node@6.9.0
Placez un fichier JPEG non sensible à l’emplacement ./hero.jpg, puis exécutez :
npx @transloadit/node@6.9.0 auth login
npx @transloadit/node@6.9.0 storage store ./hero.jpg website/hero.jpg --public --hashed
Approuvez le Workspace souhaité dans le navigateur. Vous pouvez vous y inscrire si vous n’avez pas
de compte. --public publie récursivement tout le répertoire de destination,
y compris les fichiers existants et les futurs téléversements. Utilisez un répertoire dédié
contenant uniquement des médias destinés à être publics. La commande storage store
seule ne publie pas de répertoire.
Encapsulez votre configuration next.config.ts existante :
import type { NextConfig } from 'next'
import { withTransloaditImages } from '@transloadit/viewer/next/config'
const nextConfig: NextConfig = {}
export default withTransloaditImages(nextConfig)
Dans app/page.tsx (ou src/app/page.tsx), utilisez le chemin exact
affiché par la commande de téléversement. Le hachage ci-dessous est un exemple, et non un fichier
qui existe déjà dans votre Workspace :
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
/>
)
}
Exécutez npm run dev et ouvrez la page. Ajoutez les fichiers générés
transloadit.images.json et transloadit-images.d.ts au dépôt de votre application ;
n’y ajoutez pas les informations d’authentification de la CLI. Le plugin intègre le catalogue,
la diffusion publique ne nécessite donc ni secrets de signature de l’application ni consultation
des métadonnées à l’exécution. Pour une génération de structure facultative dans une application
existante, consultez les
instructions maintenues pour image init.
Tailles adaptatives et chargement
width={960} plafonne la largeur d’affichage adaptative ; le navigateur choisit
parmi les variantes générées. Utilisez preload pour l’image importante visible
sans défilement, et non pour toutes les images d’une galerie. Les autres images sont chargées de
manière différée par défaut. Définissez sizes si votre mise en page exige
une indication de taille plus précise.
Pour un aperçu flouté, ajoutez --placeholder blur à la commande de téléversement et
placeholder="blur" à Image. L’extraction est une opération
facultative côté serveur et, lorsqu’elle réussit, ajoute une consommation de métadonnées égale à
20 % du nombre d’octets du fichier. Ne répétez pas un téléversement déjà terminé uniquement pour
ajouter un aperçu. Consultez la
référence des images adaptatives
pour les mises en page, les recadrages et le comportement des aperçus.
Conserver une origine HTTP ou S3 existante
Cette approche ne nécessite ni téléversement vers Storage ni catalogue. Installez Viewer comme ci-dessus, puis créez un Template compatible et restreint à partir de l’exemple HTTP ou S3 maintenu. Fixez l’origine ou le bucket/préfixe autorisé, exigez des signatures et désactivez les remplacements de Steps. Ne laissez pas les données du navigateur choisir des URL d’importation ou des transformations arbitraires.
Configurez une Auth Key d’application distincte pour ce Workspace avec
smart_cdn:sign, puis définissez TRANSLOADIT_SMART_CDN_KEY et
TRANSLOADIT_SMART_CDN_SECRET dans votre environnement exclusivement côté serveur.
Ne déployez pas la clé de connexion de la CLI : la déconnexion la révoque. Conservez les informations
d’authentification S3 dans les informations d’authentification à accès restreint du Template, jamais
dans du JSX ou du code de navigateur.
Effectuez le rendu dans un Server Component en fournissant les dimensions réelles de l’original issues de métadonnées fiables :
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}
/>
)
}
Remplacez le Workspace, le Template, le chemin relatif et les dimensions par vos propres valeurs.
Ce mode ne nécessite pas withTransloaditImages, sauf si vous souhaitez utiliser ses valeurs
de configuration par défaut. La diffusion directe signée implique un traitement au moment de la
requête ; pour les fichiers privés, autorisez l’accès dans le Server Component appelant, ou utilisez
la route d’autorisation par requête de la référence.
Médias privés et téléversés par les utilisateurs
Un catalogue ajouté au dépôt convient aux ressources d’un site web, mais pas à une galerie utilisateur dynamique. Pour les téléversements Uppy, les images privées et la vidéo, utilisez la recette React de reçus et de diffusion autorisée. Stockez les reçus canoniques avec leur propriétaire et vérifiez les droits d’accès actuels à chaque ressource avant de diffuser les médias. L’intégration Convex et la démonstration de mariage présentent la gestion des adhésions par l’application, aux côtés des composants réutilisables de téléversement et de diffusion.
Autres frameworks
Viewer dispose d’un modèle d’image et de gestionnaires serveur indépendants du framework, avec des adaptateurs distincts pour React et Next.js. Le plugin de configuration Next.js ci-dessus est réservé aux applications Next.js. Pour du JavaScript sans framework ou un autre framework, commencez par la recette indépendante du framework ; elle ne nécessite ni React ni Next.js. Votre application reste responsable de son interface, de son routage et de ses règles d’accès.
Vérifier votre intégration
- Dans les outils de développement du navigateur, vérifiez que les requêtes d’images atteignent le
Smart CDN de votre Workspace sans passer par
/_next/image. Redimensionnez la fenêtre d’affichage et vérifiez la taille d’image demandée. - Comparez une requête à froid à une requête répétée. La première transformation peut prendre plus de temps ; examinez les en-têtes de réponse réels plutôt que de supposer que chaque requête est mise en cache.
- Vérifiez la pertinence du texte alternatif, la stabilité de la mise en page et le comportement des aperçus dans une fenêtre d’affichage étroite.
- Pour la diffusion privée, testez avec un utilisateur non autorisé ainsi qu’avec un utilisateur autorisé. Les URL signées restent utilisables jusqu’à leur expiration ; elles ne permettent pas de révoquer l’accès aux octets déjà téléchargés.
Si une image ne s’affiche pas, utilisez les diagnostics de développement de Viewer et le guide de dépannage. Si le catalogue est perdu, récupérez les reçus plutôt que de téléverser à nouveau les fichiers. Comparez les tarifs en fonction de votre propre charge de transformation, de cache et de diffusion ; le seul fait de contourner l’optimiseur de Next ne suffit pas à établir une économie de coûts.