Téléverser une fois, transformer à l’infini

Kevin van Zonneveld

Cofondateur · Amsterdam, Pays-Bas · Afficher la bio

La plupart des pipelines d’images font un pari au moment du téléversement : générer la miniature, les versions moyenne et grande ainsi que les variantes WebP, puis les stocker à côté de l’original. Quand l’équipe design ajoute une carte carrée ou veut de l’AVIF, vous relancez un traitement par lots sur toute la bibliothèque.

Avec Transloadit Storage et le Smart CDN, vous conservez l’original et décrivez l’image dérivée dans une URL. La première requête la génère ; les requêtes suivantes peuvent utiliser le résultat mis en cache. Une nouvelle taille ou un nouveau recadrage ne nécessite ni nouveau téléversement, ni migration de toute la bibliothèque.

Stockons une photo et affichons-la sous forme de carte WebP, d’image AVIF carrée et de recadrage JPEG large. Vous n’avez besoin ni d’un Template personnalisé, ni de l’AWS CLI, ni d’un framework front-end.

Transloadit Storage est en préversion privée. Demandez-nous de l’activer pour votre Workspace. Cet exemple nécessite également Node.js 24.15+ ou 26+.

Essayer

npx @transloadit/node@latest init upload-once my-gallery
cd my-gallery
npm run demo

L’initialiseur crée un nouveau répertoire contenant des dépendances compatibles, une photo d’exemple et un petit demo.ts. Il ne téléverse rien et ne modifie aucun projet existant. La démo ouvre la connexion dans le navigateur si nécessaire, vérifie l’accès à Storage et téléverse la photo. Ouvrez gallery.html pour voir ses trois variantes.

Choisissez le Workspace voulu sur la page d’autorisation. Si vous avez besoin d’un autre compte, ouvrez le lien de connexion dans une fenêtre de navigation privée afin de conserver votre session actuelle dans la Console.

L’exemple complet et son README⁠ sont fournis avec la version publiée du SDK. Le projet généré fixe cette version, et vous pouvez modifier son code source.

Modifier la sortie, conserver l’original

En haut de demo.ts, variants définit pour chaque sortie la largeur, la hauteur, le format et la stratégie de redimensionnement. Modifiez une largeur ou un recadrage, puis relancez npm run demo. La CLI réutilise le reçu enregistré de l’original correspondant au lieu de téléverser à nouveau l’original, puis génère de nouvelles URL pour les variantes. Le terminal indique si la photo a été téléversée ou réutilisée.

Pour essayer avec votre propre photo :

npm run demo -- ./your-photo.jpg

storage store --hashed utilise un nom de fichier adressé par contenu et enregistre le reçu ressource/version dans transloadit.images.json. Conservez ce catalogue : il permet à la CLI d’éviter les téléversements répétés. Le README décrit le comportement en cas d’écrasement et la reprise si un téléversement ne se termine pas correctement.

auth smart-cdn signe les URL du pipeline publié builtin/storage-preview@0.0.3. Dans ces URL, w et h définissent la zone de sortie, f choisit le format et q règle la qualité. pad fait tenir l’image entière dans la zone ; fillcrop la remplit en recadrant. L’exemple fournit les deux dimensions.

La page obtenue contient des éléments image ordinaires qui pointent directement vers le Smart CDN. Votre application ne sert pas de proxy pour les octets des images, et demander une autre variante ne modifie pas l’original.

De cet exemple à votre application

La démo utilise vos informations d’identification locales de la CLI et crée des URL d’accès signées temporaires. Elle ne publie aucun répertoire, mais un téléversement dans un répertoire déjà public ne rend pas ce répertoire privé. Gardez gallery.html privé : toute personne disposant de ses URL peut accéder à ces images dérivées jusqu’à leur expiration. L’exemple arrondit l’expiration à l’heure pleine, ce qui donne une à deux heures d’accès et une meilleure réutilisation des URL. Régénérez la page lorsque les URL expirent. Les durées de cache réelles proviennent de l’en-tête Cache-Control de la réponse ; l’expiration ne peut pas rappeler les octets que quelqu’un a déjà téléchargés.

Pour une application déployée, utilisez des informations d’identification distinctes pour le téléversement et une clé de diffusion réservée au serveur avec smart_cdn:sign. La déconnexion de la CLI connectée via le navigateur révoque la clé de connexion : ne la déployez donc pas comme clé d’application. Authentifiez les utilisateurs et vérifiez leur droit d’accès à leurs enregistrements de ressources sauvegardés avant de signer. N’exposez jamais un point de terminaison qui signe des identifiants de ressource ou des paramètres de transformation arbitraires fournis par le navigateur.

Choisissez l’intégration adaptée à votre application :

• Téléversements côté serveur : utilisez la fonction utilitaire storeImage()⁠ du SDK Node et enregistrez le reçu renvoyé avec son propriétaire. Les téléversements existants via S3 ou via une Assembly peuvent également renvoyer des enregistrements Storage canoniques ; n’inventez pas d’identifiants de ressource à partir des noms de fichiers.
• React ou Next.js : utilisez l’intégration image et Viewer⁠ pour le rendu responsive, les états de chargement et les galeries. Viewer est une version alpha publiée ; fixez la version que vous testez. Les projets Next.js existants peuvent utiliser image init sans créer d’autre application.
• Galeries de fichiers téléversés par les utilisateurs : la démo de mariage Convex⁠ combine des téléversements Uppy, des requêtes réactives sur les reçus et une diffusion autorisée de photos et vidéos. Elle s’appuie sur les mêmes identités Storage et fonctions utilitaires de diffusion, tandis que l’application définit ses propres règles d’accès pour les invités.

Que se passe-t-il lorsque vous remplacez un fichier ?

La paire ressource/version sélectionne exactement les octets conservés, et non « ce qui se trouve à ce chemin aujourd’hui ». Un déplacement dans Storage préserve cette identité. Un écrasement crée une nouvelle version : enregistrez son nouveau reçu pour afficher le remplacement. Les anciennes URL fixées sur une version renvoient toujours à l’ancienne version tant qu’elle est conservée et accessible. Ici, v est le véritable identifiant de version Storage, et non un v=2 servant à contourner le cache.

Le même Built-in peut prévisualiser un PDF ou une vidéo stockés à l’aide de l’enregistrement ressource/version propre à ce fichier. La commande storage store de l’exemple est destinée aux images ; pour les autres médias, utilisez un téléversement via une Assembly ou via S3, puis récupérez les enregistrements canoniques de ces fichiers. Pour un traitement spécialisé, utilisez URL Transform avec un Template personnalisé qui exige une signature, en vérifiant la prise en charge du Smart CDN par chaque Robot. Les traitements vidéo plus lourds relèvent d’une Assembly dont vous stockez les résultats pour la diffusion.

Commencez par l’exemple exécutable⁠, modifiez une variante et conservez votre original.