Faça upload uma vez, transforme para sempre
A maioria dos pipelines de imagem faz uma aposta no momento do upload: gerar a miniatura e as variantes média, grande e WebP, e depois armazená-las ao lado do original. Quando o time de design adiciona um card quadrado ou quer AVIF, você precisa rodar outro processamento em lote em toda a biblioteca.
Com o Transloadit Storage e o Smart CDN, você mantém o original e descreve o derivado em uma URL. A primeira requisição o renderiza; as requisições seguintes podem usar o resultado em cache. Um novo tamanho ou recorte não exige outro upload nem uma migração de toda a biblioteca.
Vamos armazenar uma foto e exibi-la como um card WebP, uma imagem AVIF quadrada e um recorte JPEG largo. Não é preciso Template personalizado, AWS CLI nem framework de front-end.
O Transloadit Storage está em prévia privada. Fale conosco para habilitá-lo no seu Workspace. Você também vai precisar do Node.js 24.15+ ou Node.js 26+ para este exemplo.
Experimente
npx @transloadit/node@latest init upload-once my-gallery
cd my-gallery
npm run demo
O inicializador cria um novo diretório com dependências compatíveis, uma foto de exemplo e um
pequeno demo.ts. Ele não faz upload de nada nem altera um projeto existente. A demonstração abre o
login no navegador quando necessário, verifica o acesso ao Storage e faz o upload da foto. Abra
gallery.html para ver as três variantes.
Escolha o Workspace pretendido na página de aprovação. Se precisar de outra conta, abra o link de login em uma janela privada do navegador para manter sua sessão atual no Console.
pad; fillcrop preenche o quadro largo.O exemplo completo e o README acompanham a versão do SDK. O projeto gerado fixa essa versão, e você pode editar o código-fonte dele.
Altere a saída, mantenha o original
No topo de demo.ts, variants define a largura, a altura, o formato e a estratégia de
redimensionamento de cada saída. Altere uma largura ou um recorte e execute npm run demo novamente. A CLI
reutiliza o recibo salvo do original correspondente em vez de fazer upload dele de novo e, em
seguida, gera URLs novas para as variantes. O terminal informa se foi feito upload da foto ou se
ela foi reutilizada.
Para testar com a sua própria foto:
npm run demo -- ./your-photo.jpg
storage store --hashed usa um nome de arquivo endereçado por conteúdo e salva o recibo de asset/versão em
transloadit.images.json. Guarde esse catálogo: ele permite que a CLI evite uploads repetidos. O README
explica o comportamento de sobrescrita e de recuperação caso um upload não termine corretamente.
auth smart-cdn assina URLs para o pipeline builtin/storage-preview@0.0.3 publicado. Nessas URLs, w e
h definem a caixa de saída, f escolhe o formato e q define a qualidade. pad encaixa a
imagem inteira dentro da caixa; fillcrop a preenche recortando. O exemplo fornece as duas dimensões.
A página resultante contém elementos de imagem comuns que apontam diretamente para o Smart CDN. Sua aplicação não faz proxy dos bytes das imagens, e solicitar outra variante não modifica o original.
Deste exemplo para a sua aplicação
A demonstração usa suas credenciais locais da CLI e cria URLs de acesso assinadas temporárias. Ela
não publica nenhum diretório, mas fazer upload para um diretório que já é público não o torna
privado. Mantenha gallery.html privado: qualquer pessoa com as URLs dele pode acessar esses derivados até
que elas expirem. O exemplo arredonda a expiração para uma hora cheia, com o objetivo de oferecer de
uma a duas horas de acesso e melhorar a reutilização das URLs. Gere a página novamente quando as
URLs expirarem. Os tempos reais de cache vêm do cabeçalho Cache-Control da resposta; a expiração não
tem como revogar as cópias dos bytes que alguém já baixou.
Para uma aplicação implantada, use credenciais de upload separadas e uma chave de entrega exclusiva
do servidor com smart_cdn:sign. Fazer logout da CLI com login pelo navegador revoga a chave de login,
então não implante essa chave como chave da aplicação. Autentique os usuários e verifique o acesso
deles aos registros de assets salvos antes de assinar. Nunca exponha um endpoint que assine IDs de
assets ou parâmetros de transformação arbitrários fornecidos pelo navegador.
Escolha a integração adequada ao seu app:
- Uploads no servidor: use o
helper
storeImage()do SDK para Node e salve o recibo retornado junto com o respectivo proprietário. Uploads existentes via S3 e Assembly também podem retornar registros canônicos do Storage; não invente IDs de assets a partir de nomes de arquivo. - React ou Next.js: use a
integração de imagem e Viewer
para renderização responsiva, estados de carregamento e galerias. O Viewer é uma versão alpha
publicada; fixe a versão que você testar. Projetos Next.js existentes podem usar
image init, sem criar outro app. - Galerias com upload dos usuários: a demonstração de casamento com Convex combina uploads com Uppy, consultas reativas de recibos e entrega autorizada de fotos/vídeos. Ela se baseia nas mesmas identidades do Storage e nos mesmos helpers de entrega, com regras de acesso de convidados definidas pela própria aplicação.
O que acontece quando você substitui um arquivo?
O par asset/versão seleciona exatamente os bytes retidos, não “o que estiver neste caminho hoje”.
Mover um arquivo no Storage preserva essa identidade. Uma sobrescrita cria uma nova versão: salve o
novo recibo dela para exibir a substituição. URLs antigas fixadas em uma versão continuam se
referindo à versão antiga enquanto ela estiver retida e acessível. Aqui, v é o ID de versão
real do Storage, não um cachebuster v=2.
O mesmo Built-in pode pré-visualizar um PDF ou vídeo armazenado usando o próprio registro de
asset/versão desse arquivo. O comando storage store do exemplo é para imagens; para outras mídias, use
uma Assembly ou um upload via S3 e obtenha os registros canônicos delas. Para processamento
especializado, use, por meio do URL Transform, um Template
personalizado que exija assinatura, verificando o suporte de cada Robot ao Smart CDN.
Processamentos de vídeo mais pesados devem ficar em uma Assembly cujos resultados você armazena para
entrega.
Comece pelo exemplo executável, altere uma variante e mantenha o seu original.