Viewer para Next.js
@transloadit/viewer renderiza imágenes adaptables cuyos bytes provienen directamente de
Smart CDN, sin pasar por la optimización de imágenes de Next.js. Usa originales de Transloadit Storage
o conserva tu origen HTTP/S3 existente. No necesitas migrar tus archivos para usar la integración.
Viewer está en fase alfa. Esta guía usa
@transloadit/viewer@0.1.0, Next.js 16.3.3+ con App Router, React 19 y el entorno de ejecución de Node.js. Fija la versión de Viewer que pruebes. Su componenteImageno sustituye directamente aloaderFilepara elnext/imageestándar.
Empieza con imágenes públicas de Storage
Usa esta vía para imágenes públicas de sitios web que se gestionan junto con tu código. Para medios privados o subidos por usuarios, usa la integración con aplicaciones. Storage está en vista previa privada; pídenos que lo habilitemos primero para tu Workspace.
En tu proyecto Next.js existente, instala los paquetes publicados. Estos ejemplos usan npm; conserva el gestor de paquetes y el archivo de bloqueo de tu proyecto si ya usa Yarn o pnpm.
npm install --save-exact @transloadit/viewer@0.1.0
npm install --save-dev --save-exact @transloadit/node@6.9.0
Coloca un JPEG sin información sensible en ./hero.jpg y luego ejecuta:
npx @transloadit/node@6.9.0 auth login
npx @transloadit/node@6.9.0 storage store ./hero.jpg website/hero.jpg --public --hashed
Aprueba el Workspace previsto en el navegador. Puedes registrarte allí si no tienes una cuenta.
--public publica todo el directorio de destino de forma recursiva, incluidos
los archivos existentes y las subidas futuras. Usa un directorio exclusivo que contenga solo medios
destinados a ser públicos. storage store por sí solo no publica un directorio.
Envuelve tu configuración existente de next.config.ts:
import type { NextConfig } from 'next'
import { withTransloaditImages } from '@transloadit/viewer/next/config'
const nextConfig: NextConfig = {}
export default withTransloaditImages(nextConfig)
En app/page.tsx (o src/app/page.tsx), usa la ruta exacta que muestra
el comando de subida. El hash siguiente es un ejemplo, no un archivo que ya exista en tu 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
/>
)
}
Ejecuta npm run dev y abre la página. Incluye los archivos generados
transloadit.images.json y transloadit-images.d.ts en el control de versiones junto con
tu aplicación; no incluyas las credenciales de la CLI. El plugin empaqueta el catálogo, por lo que la
entrega pública no necesita secretos de firma de la aplicación ni consultas de metadatos en tiempo
de ejecución. Para generar una estructura inicial opcional en una aplicación existente, consulta las
instrucciones actualizadas de image init.
Tamaños adaptables y carga
width={960} limita el ancho de visualización adaptable; el navegador selecciona
entre las opciones generadas. Usa preload para la imagen importante visible
sin desplazamiento, no para todas las imágenes de una galería. Las demás imágenes se cargan de forma
diferida de manera predeterminada. Configura sizes cuando tu diseño necesite
una indicación de tamaño más precisa.
Para obtener un marcador de posición desenfocado, añade --placeholder blur al comando de
subida y placeholder="blur" a Image. La extracción es un trabajo
opcional del lado del servidor y, cuando se completa correctamente, añade un uso de metadatos
equivalente al 20 % de los bytes del archivo. No repitas una subida ya completada solo para añadir un
marcador de posición. Consulta la referencia de imágenes adaptables
para conocer los diseños, los recortes y el comportamiento de los marcadores de posición.
Conserva un origen HTTP o S3 existente
Esta vía no necesita subidas a Storage ni catálogo. Instala Viewer como se indica arriba y luego crea un Template compatible y restringido con el ejemplo actualizado de HTTP o S3. Fija el origen o bucket/prefijo permitido, exige firmas y deshabilita la sobrescritura de Steps. No permitas que los datos de entrada del navegador elijan URL de importación o transformaciones arbitrarias.
Configura una Auth Key de aplicación independiente para ese Workspace con
smart_cdn:sign y establece TRANSLOADIT_SMART_CDN_KEY y
TRANSLOADIT_SMART_CDN_SECRET en tu entorno exclusivo del servidor.
No despliegues la clave de inicio de sesión de la CLI: cerrar sesión la revoca. Mantén las
credenciales de S3 entre las credenciales restringidas del Template, nunca en JSX ni en código del
navegador.
Renderiza en un Server Component y proporciona las dimensiones reales del original a partir de metadatos de confianza:
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}
/>
)
}
Reemplaza el Workspace, el Template, la ruta relativa y las dimensiones por tus propios valores.
Este modo no requiere withTransloaditImages, salvo que quieras usar sus valores de
configuración predeterminados. La entrega directa firmada requiere trabajo al recibir cada solicitud;
para archivos privados, autoriza el acceso en el Server Component que realiza la llamada o usa la
ruta de autorización por solicitud de la referencia.
Medios privados y subidos por usuarios
Un catálogo incluido en el control de versiones es adecuado para los activos del sitio web, no para una galería dinámica de usuarios. Para subidas con Uppy, imágenes privadas y video, usa la guía de comprobantes de React y entrega autorizada. Almacena los comprobantes canónicos junto con su propietario y comprueba el acceso vigente a cada activo antes de servir los medios. La integración con Convex y la demo de bodas muestran la gestión de membresía a cargo de la aplicación junto con los componentes reutilizables de subida y entrega.
Otros frameworks
Viewer tiene un modelo de imágenes y manejadores de servidor independientes del framework, con adaptadores separados para React y Next.js. El plugin de configuración de Next.js mostrado arriba solo sirve para aplicaciones Next.js. Para JavaScript puro u otro framework, empieza con la guía independiente del framework; no requiere React ni Next.js. Tu aplicación sigue siendo responsable de su interfaz, sus rutas y sus reglas de acceso.
Verifica tu integración
- En las herramientas para desarrolladores del navegador, verifica que las solicitudes de imágenes
lleguen a Smart CDN de tu Workspace y no pasen por
/_next/image. Cambia el tamaño del área de visualización y comprueba el tamaño de imagen solicitado. - Compara una solicitud sin caché con una solicitud repetida. La primera transformación puede tardar más; inspecciona los encabezados reales de respuesta en lugar de suponer que todas las solicitudes están en caché.
- Confirma que el texto alternativo sea útil, que el diseño sea estable y que los marcadores de posición se comporten correctamente en un área de visualización estrecha.
- Para la entrega privada, prueba tanto con un usuario no autorizado como con uno autorizado. Las URL firmadas siguen siendo utilizables hasta que vencen; no pueden retirar bytes ya descargados.
Si una imagen falla, usa los diagnósticos de desarrollo de Viewer y la guía de solución de problemas. Si se pierde el catálogo, recupera los comprobantes en lugar de volver a subir los archivos. Compara los precios según tu propia carga de transformación, caché y entrega; omitir el optimizador de Next por sí solo no demuestra un ahorro de costos.