Node SDK v4: foco em TypeScript e suporte abrangente a Robots

Kevin van Zonneveld

Cofundador · Amsterdã, Países Baixos ·

Hoje estamos lançando a versão 4 do nosso SDK para Node.js, a maior reformulação do pacote desde o seu lançamento inicial. Agora você pode contar com cobertura abrangente de TypeScript, definições completas dos Robots com autocomplete, tratamento estruturado de erros e ferramentas modernas. Tudo isso respeitando a trajetória de quinze anos de uma API que cresceu junto com o ecossistema Node.

Novidades da v4

O Node SDK v4 é uma reescrita completa em TypeScript, com estas melhorias importantes:

Design com foco em TypeScript

Cada Robot, parâmetro e resposta agora tem tipagem completa. Ao escrever Assembly Instructions, sua IDE sugere os Robots, parâmetros e valores de retorno corretos enquanto você digita:

import { Transloadit } from 'transloadit'

const transloadit = new Transloadit({
  authKey: process.env.TRANSLOADIT_KEY,
  authSecret: process.env.TRANSLOADIT_SECRET,
})

await transloadit.createAssembly({
  params: {
    steps: {
      resize: {
        use: ':original',
        robot: '/image/resize', // ← autocompletes all available Robots
        width: 320, // ← only shows valid parameters for this Robot
        height: 240,
        result: true,
      },
    },
  },
  waitForCompletion: true,
})

As Assembly Instructions são validadas com base em tipos ricos, o que detecta problemas de configuração ou de retrocompatibilidade cedo, durante o desenvolvimento local, e não no meio de um deploy.

Ambiente JavaScript moderno

O SDK agora é ESM puro, tem como alvo o Node.js 20+ e usa exportações nomeadas em todo o código:

// Named exports replace the default export
import { Transloadit } from 'transloadit'

Para projetos CommonJS, use importações dinâmicas:

async function getClient() {
  const { Transloadit } = await import('transloadit')
  return new Transloadit({ authKey, authSecret })
}

Tratamento de erros aprimorado

Nossos erros agora incluem stack traces detalhados, com mais contexto para facilitar a depuração.

Helper de URLs do Smart CDN

Gere URLs assinadas do Smart CDN diretamente pelo SDK:

const signedUrl = transloadit.getSignedSmartCDNUrl({
  workspace: 'my-team',
  template: 'hero-image',
  input: 'photo.jpg',
  urlParams: { format: 'webp' },
})

Nossa abordagem para adicionar tipos retroativamente

Ao adicionar TypeScript a uma API que evoluiu organicamente ao longo de quinze anos, enfrentamos um desafio interessante. Nossa API surgiu nos primeiros dias do Node.js, quando o JavaScript era muito mais permissivo, em uma época em que a tipagem dinâmica era a norma.

Em vez de criar definições de tipos idealizadas que quebrariam integrações existentes, escolhemos uma abordagem pragmática:

Modelar o que existe: nossos tipos refletem com precisão a superfície atual da API, mesmo quando isso significa aceitar padrões longe do ideal.
Testar tudo: cada definição de tipo passa pelo nosso ambiente de testes para garantir que corresponda ao comportamento real da API.
Iterar rumo à beleza: com tipos precisos como base, podemos refinar gradualmente tanto os schemas quanto a própria API, sempre garantindo a retrocompatibilidade.
Preservar a compatibilidade: onde a API tem peculiaridades, nós as documentamos em vez de forçar mudanças imediatas.

Essa abordagem significa que, de início, nossos tipos talvez não ganhem concursos de beleza. Você pode encontrar unions onde esperaria um único tipo, ou campos opcionais que logicamente deveriam ser obrigatórios. Isso é intencional: estamos capturando quinze anos de evolução da API, durante os quais diferentes endpoints cresceram em momentos diferentes, com convenções diferentes.

Ao adotar essa abordagem ponderada, garantimos que o código existente continue funcionando, que o código novo receba a orientação adequada e que melhorias futuras continuem possíveis. Acreditamos que desenvolvedores valorizam mais a honestidade do que o idealismo. Nossos tipos dizem a verdade sobre a nossa API, com peculiaridades e tudo.

Guia de migração

Migrar da v3 para a v4 exige algumas mudanças importantes:

Checklist rápido de atualização

Atualize para transloadit@^4.0.0 e confira se você está no Node.js 20 ou mais recente
Troque as importações padrão por importações nomeadas
Remova as chamadas require do CommonJS (use importações dinâmicas no lugar)
Ative o TypeScript ou adicione tipagens JSDoc para ter um suporte melhor no editor
Atualize o tratamento de erros se você usa classes de erro personalizadas
Rode seus testes de integração com validateResponses ativado para detectar surpresas nos schemas. Por favor, avise a gente se estiver recebendo algum erro, e vamos corrigi-lo.

Validação de respostas (opcional)

Ative a validação em tempo de execução das respostas da API durante o desenvolvimento:

const transloadit = new Transloadit({
  authKey,
  authSecret,
  validateResponses: true, // This runs API responses through Zod, so you can have more confidence in the types. This will become the default in 5.x, but for this release it still defaults to false
})

Melhorias na experiência de desenvolvimento

O novo SDK se integra perfeitamente a fluxos de trabalho modernos:

Suporte completo ao IntelliSense no VS Code e em outras IDEs
Comentários JSDoc detalhados para todos os métodos e parâmetros
Source maps para facilitar a depuração
Compatibilidade com a verificação estrita de nulos (strict null checking)

Primeiros passos

Instale o novo SDK:

npm install transloadit@^4.0.0

Crie um cliente e comece a desenvolver:

import { Transloadit } from 'transloadit'

const transloadit = new Transloadit({
  authKey: 'YOUR_AUTH_KEY',
  authSecret: 'YOUR_AUTH_SECRET',
})

// TypeScript knows exactly what's available
const assembly = await transloadit.createAssembly({
  params: {
    steps: {
      optimize: {
        use: ':original',
        robot: '/image/optimize',
      },
    },
  },
})

O que vem por aí?

Esta versão v4 é só o começo da nossa jornada com TypeScript. À medida que continuamos refinando nossa API e nossos schemas, você verá tipos ainda mais precisos, documentação melhor gerada a partir das definições de tipos, mensagens de erro aprimoradas e refinamentos graduais nos schemas que mantêm a compatibilidade.

Experimente hoje

O Node SDK v4 já está disponível no npm e no GitHub. Confira o guia de migração para ver instruções detalhadas de atualização e conte para a gente o que achou!

Pronto para começar? Crie uma conta gratuita e experimente você mesmo o novo SDK baseado em TypeScript.

Atualização de 2 de fevereiro de 2026: agora também oferecemos @transloadit/zod/v3, @transloadit/zod/v4, @transloadit/types, caso você precise dos nossos schemas ou tipos sem incluir o SDK completo para Node.js. Além disso, o SDK passou a se chamar @transloadit/node, enquanto o transloadit continuará disponível como um clone dele, para manter a retrocompatibilidade.