Sube una vez, transforma para siempre
La mayoría de los pipelines de imágenes hacen una apuesta en el momento de la subida: generan la miniatura y las variantes mediana, grande y WebP, y las almacenan junto al original. Cuando el equipo de diseño añade una tarjeta cuadrada o quiere AVIF, ejecutas otro trabajo por lotes sobre toda la biblioteca.
Con Transloadit Storage y la Smart CDN, conservas el original y describes el derivado en una URL. La primera solicitud lo genera; las siguientes pueden usar el resultado en caché. Un nuevo tamaño o recorte no requiere otra subida ni una migración de toda la biblioteca.
Vamos a almacenar una foto y mostrarla como una tarjeta WebP, una imagen AVIF cuadrada y un recorte JPEG panorámico. No necesitas un Template personalizado, la AWS CLI ni un framework de front-end.
Transloadit Storage está en vista previa privada. Pídenos que lo habilitemos para tu Workspace. También necesitarás Node.js 24.15+ o Node.js 26+ para este ejemplo.
Pruébalo
npx @transloadit/node@latest init upload-once my-gallery
cd my-gallery
npm run demo
El inicializador crea un directorio nuevo con dependencias compatibles, una foto de ejemplo y un
pequeño demo.ts. No sube nada ni modifica ningún proyecto existente. La demo abre el inicio de sesión
en el navegador cuando hace falta, comprueba el acceso a Storage y sube la foto. Abre gallery.html para ver
sus tres variantes.
Elige el Workspace correcto en la página de aprobación. Si necesitas otra cuenta, abre el enlace de inicio de sesión en una ventana privada del navegador para conservar tu sesión actual en la Console.
pad; fillcrop llena el encuadre panorámico.El ejemplo completo y su README se distribuyen con la versión del SDK. El proyecto generado fija esa versión y puedes editar su código fuente.
Cambia la salida y conserva el original
Al principio de demo.ts, variants define el ancho, el alto, el formato y la estrategia de
redimensionado de cada salida. Cambia un ancho o un recorte y vuelve a ejecutar npm run demo. La CLI
reutiliza el recibo guardado del original coincidente en lugar de volver a subirlo y luego genera
URL nuevas para las variantes. La terminal indica si la foto se subió o se reutilizó.
Para probar con tu propia foto:
npm run demo -- ./your-photo.jpg
storage store --hashed usa un nombre de archivo direccionado por contenido y guarda el recibo de activo/versión en
transloadit.images.json. Conserva ese catálogo: permite que la CLI omita subidas repetidas. El README explica
el comportamiento de sobrescritura y recuperación si una subida no termina correctamente.
auth smart-cdn firma URL para el pipeline publicado builtin/storage-preview@0.0.3. En estas URL, w y h definen el
cuadro de salida, f elige el formato y q define la calidad. pad encaja la imagen completa
dentro del cuadro; fillcrop lo llena recortando. El ejemplo proporciona ambas dimensiones.
La página resultante contiene elementos de imagen normales que apuntan directamente a la Smart CDN. Tu aplicación no hace de proxy de los bytes de las imágenes, y solicitar otra variante no modifica el original.
De este ejemplo a tu aplicación
La demo usa tus credenciales locales de la CLI y crea URL de acceso firmadas temporales. No publica
ningún directorio, pero subir a un directorio que ya es público no lo vuelve privado.
Mantén gallery.html en privado: cualquiera que tenga sus URL puede acceder a esos derivados hasta que
caduquen. El ejemplo redondea la caducidad a una hora en punto, lo que da entre una y dos horas de
acceso y una mejor reutilización de las URL. Vuelve a generar la página cuando caduquen las URL. La
duración real de la caché proviene del encabezado Cache-Control de la respuesta; la caducidad no puede
retirar ni deshacer las copias de los bytes que alguien ya descargó.
Para una aplicación desplegada, usa credenciales de subida separadas y una clave de entrega solo de
servidor con smart_cdn:sign. Cerrar la sesión de la CLI iniciada desde el navegador revoca la clave de inicio
de sesión, así que no la despliegues como clave de aplicación. Autentica a los usuarios y comprueba
su acceso a los registros de activos guardados antes de firmar. Nunca expongas un endpoint que firme
IDs de activos o parámetros de transformación arbitrarios enviados por el navegador.
Elige la integración que se ajuste a tu aplicación:
- Subidas del lado del servidor: usa el
helper
storeImage()del SDK de Node y guarda el recibo devuelto junto con su propietario. Las subidas existentes con S3 y Assembly también pueden devolver registros canónicos de Storage; no inventes IDs de activos a partir de nombres de archivo. - React o Next.js: usa la
integración de imagen y Viewer
para renderizado adaptable, estados de carga y galerías. Viewer es una versión alfa publicada;
fija la versión que pruebes. Los proyectos de Next.js existentes pueden usar
image initsin crear otra aplicación. - Galerías con contenido subido por usuarios: la demo de boda con Convex combina subidas con Uppy, consultas reactivas de recibos y entrega autorizada de fotos/videos. Se basa en las mismas identidades de Storage y los mismos helpers de entrega, con reglas de acceso para invitados definidas por la aplicación.
¿Qué pasa cuando reemplazas un archivo?
El par activo/versión selecciona bytes exactos conservados, no «lo que haya en esta ruta hoy». Un
movimiento en Storage conserva esa identidad. Una sobrescritura crea una nueva versión: guarda su
nuevo recibo para mostrar el reemplazo. Las URL antiguas fijadas a una versión siguen apuntando a la
versión anterior mientras se conserve y sea accesible. Aquí, v es el ID real de la versión de
Storage, no un cachebuster v=2.
El mismo Built-in puede previsualizar un PDF o un video almacenado usando el propio registro de
activo/versión de ese archivo. El comando storage store del ejemplo es para imágenes; usa una subida con
Assembly o S3 para otros medios y recupera sus registros canónicos. Para procesamiento
especializado, usa URL Transform con un Template personalizado que requiera firma y
comprueba la compatibilidad de cada Robot con la Smart CDN. El trabajo de video más pesado
corresponde a una Assembly cuyos resultados almacenas para su entrega.
Empieza con el ejemplo ejecutable, cambia una variante y conserva tu original.