Viewer para Next.js
@transloadit/viewer renderiza imagens responsivas cujos bytes vêm diretamente do Smart CDN,
sem passar pela otimização de imagens do Next.js. Use originais no Transloadit Storage ou mantenha
sua origem HTTP/S3 existente. Você não precisa migrar seus arquivos para usar a integração.
O Viewer está em versão alfa. Este guia usa
@transloadit/viewer@0.1.0, Next.js 16.3.3+ com o App Router, React 19 e o runtime do Node.js. Fixe a versão do Viewer que você testar. Seu componenteImagenão substitui diretamente oloaderFilepadrão denext/image.
Comece com imagens públicas no Storage
Use esta opção para imagens públicas do site gerenciadas junto com seu código. Para mídias privadas ou enviadas por usuários, use a integração com a aplicação. O Storage está em prévia privada; peça à nossa equipe que o habilite para seu Workspace primeiro.
No seu projeto Next.js existente, instale os pacotes publicados. Estes exemplos usam npm; mantenha o gerenciador de pacotes e o arquivo de lock do projeto se ele já usar Yarn ou pnpm.
npm install --save-exact @transloadit/viewer@0.1.0
npm install --save-dev --save-exact @transloadit/node@6.9.0
Coloque um JPEG sem dados sensíveis em ./hero.jpg e execute:
npx @transloadit/node@6.9.0 auth login
npx @transloadit/node@6.9.0 storage store ./hero.jpg website/hero.jpg --public --hashed
Aprove o Workspace desejado no navegador. Você pode criar uma conta ali se ainda não tiver uma.
--public publica todo o diretório de destino recursivamente, incluindo arquivos
existentes e uploads futuros. Use um diretório dedicado contendo apenas mídias destinadas ao
acesso público. Usar apenas storage store não publica um diretório.
Envolva sua configuração existente de next.config.ts:
import type { NextConfig } from 'next'
import { withTransloaditImages } from '@transloadit/viewer/next/config'
const nextConfig: NextConfig = {}
export default withTransloaditImages(nextConfig)
Em app/page.tsx (ou src/app/page.tsx), use o caminho exato exibido pelo comando de upload.
O hash abaixo é um exemplo, não um arquivo que já existe no seu 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
/>
)
}
Execute npm run dev e abra a página. Inclua os arquivos gerados transloadit.images.json e
transloadit-images.d.ts no commit do seu app; não inclua as credenciais da CLI. O plugin empacota o
catálogo, portanto a entrega pública não exige segredos de assinatura da aplicação nem consultas de
metadados em tempo de execução. Para estruturação opcional em um app existente, consulte as
instruções mantidas de image init.
Tamanhos responsivos e carregamento
width={960} limita a largura de exibição responsiva; o navegador seleciona entre as opções geradas.
Use preload para a imagem importante visível sem rolagem, não para todas as imagens de uma galeria.
As demais imagens usam carregamento sob demanda por padrão. Defina sizes
quando seu layout precisar de uma indicação de tamanho mais precisa.
Para um placeholder desfocado, adicione --placeholder blur ao comando de upload e placeholder="blur"
a Image. A extração é um processamento opcional no servidor e acrescenta uso de metadados
equivalente a 20% dos bytes do arquivo quando bem-sucedida. Não repita um upload já concluído apenas
para adicionar um placeholder. Consulte a referência de imagens responsivas
para saber mais sobre layouts, recortes e comportamento dos placeholders.
Mantenha uma origem HTTP ou S3 existente
Esta opção não exige upload para o Storage nem catálogo. Instale o Viewer como descrito acima e crie um Template compatível e restrito usando o exemplo mantido de HTTP ou S3. Fixe a origem ou o bucket/prefixo permitido, exija assinaturas e desative as substituições de Steps. Não permita que entradas do navegador escolham URLs de importação ou transformações arbitrárias.
Configure uma Auth Key separada da aplicação para esse Workspace com smart_cdn:sign e defina
TRANSLOADIT_SMART_CDN_KEY e TRANSLOADIT_SMART_CDN_SECRET no ambiente exclusivo do servidor.
Não implante a chave de login da CLI: encerrar a sessão a revoga. Mantenha as credenciais do S3 nas
credenciais restritas do Template, nunca em JSX ou no código do navegador.
Renderize em um Server Component, fornecendo as dimensões originais reais obtidas de metadados confiáveis:
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}
/>
)
}
Substitua o Workspace, o Template, o caminho relativo e as dimensões pelos seus próprios valores.
Este modo não exige withTransloaditImages, a menos que você queira seus padrões de configuração.
A entrega direta assinada é processada no momento da requisição; autorize o acesso a arquivos
privados no Server Component que faz a chamada ou use a rota de autorização por requisição da referência.
Mídias privadas e enviadas por usuários
Um catálogo incluído no commit é adequado para os recursos de um site, não para uma galeria dinâmica de usuários. Para uploads com o Uppy, imagens privadas e vídeos, use a receita de recibos e entrega autorizada para React. Armazene os recibos canônicos junto com seu proprietário e verifique o acesso atual a cada recurso antes de servir a mídia. A integração com o Convex e a demonstração de casamento mostram o gerenciamento de membros pela aplicação junto com os componentes reutilizáveis de upload e entrega.
Outros frameworks
O Viewer tem um modelo de imagem independente de framework e manipuladores no servidor, com adaptadores separados para React e Next.js. O plugin de configuração do Next.js acima é exclusivo para apps Next.js. Para JavaScript puro ou outro framework, comece pela receita independente de framework; ela não exige React nem Next.js. Sua aplicação continua responsável pela interface, pelo roteamento e pelas regras de acesso.
Verifique sua integração
- Nas ferramentas de desenvolvedor do navegador, verifique se as requisições de imagens chegam ao
Smart CDN do seu Workspace e não passam por
/_next/image. Redimensione a área de visualização e confira o tamanho de imagem solicitado. - Compare uma requisição sem cache com uma requisição repetida. A primeira transformação pode demorar mais; inspecione os cabeçalhos reais da resposta em vez de presumir que toda requisição está em cache.
- Confirme se o texto alternativo é útil, se o layout é estável e se o placeholder se comporta como esperado em uma área de visualização estreita.
- Para entrega privada, teste tanto um usuário não autorizado quanto um autorizado. As URLs assinadas continuam utilizáveis até expirarem; elas não podem revogar o acesso a bytes já baixados.
Se uma imagem falhar, use os diagnósticos de desenvolvimento do Viewer e o guia de solução de problemas. Se o catálogo for perdido, recupere os recibos em vez de fazer o upload novamente. Compare os preços considerando sua própria carga de transformações, cache e entrega; contornar o otimizador do Next, por si só, não comprova uma economia de custos.