SDK Node v4 : TypeScript d’abord, support complet des Robots

Kevin van Zonneveld

Cofondateur · Amsterdam, Pays-Bas · Afficher la bio

Aujourd’hui, nous publions la version 4 de notre SDK Node.js, la refonte la plus importante du paquet depuis son lancement initial. Vous pouvez désormais compter sur un typage TypeScript complet, des définitions complètes des Robots avec autocomplétion, une gestion structurée des erreurs et des outils modernes — tout en respectant les quinze années d’évolution d’une API qui a grandi aux côtés de l’écosystème Node.

Les nouveautés de la v4

Le SDK Node v4 a été entièrement réécrit en TypeScript et apporte les améliorations majeures suivantes :

Une conception axée sur TypeScript

Chaque Robot, chaque paramètre et chaque réponse dispose désormais d’un typage complet. Lorsque vous rédigez des Assembly Instructions, votre IDE suggère les Robots, les paramètres et les valeurs de retour appropriés au fil de votre saisie :

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,
})

Les Assembly Instructions sont validées à l’aide de types détaillés, ce qui permet de détecter les problèmes de configuration ou de rétrocompatibilité dès le développement local, plutôt qu’en plein déploiement.

Un environnement JavaScript moderne

Le SDK utilise désormais exclusivement ESM et cible Node.js 20+, avec des exports nommés partout :

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

Pour les projets CommonJS, utilisez des imports dynamiques :

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

Une gestion des erreurs améliorée

Nos erreurs incluent désormais des traces de pile détaillées avec davantage de contexte pour faciliter le débogage.

Un utilitaire pour les URL du Smart CDN

Générez des URL signées du Smart CDN directement depuis le SDK :

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

Notre approche pour ajouter le typage à l’existant

L’ajout de TypeScript à une API qui a évolué progressivement pendant quinze ans nous a posé un défi intéressant. Notre API a vu le jour aux débuts de Node.js, quand JavaScript était bien plus permissif — à une époque où le typage dynamique était la norme.

Plutôt que de créer des définitions de types idéalisées qui rendraient les intégrations existantes incompatibles, nous avons choisi une approche pragmatique :

1. Modéliser l’existant : nos types reflètent fidèlement l’interface actuelle de l’API, même lorsque cela implique d’accepter des modèles imparfaits.

2. Tout tester : chaque définition de type passe par notre infrastructure de test pour vérifier qu’elle correspond au comportement réel de l’API.

3. Affiner progressivement la conception : en nous appuyant sur des types fidèles à l’existant, nous pouvons améliorer progressivement les schémas et l’API elle-même — tout en garantissant toujours la rétrocompatibilité.

4. Préserver la compatibilité : lorsque l’API présente des particularités, nous les documentons plutôt que d’imposer des changements immédiats.

Avec cette approche, nos types ne remporteront peut-être pas de concours de beauté dans un premier temps. Vous verrez peut-être des unions là où vous attendriez un seul type, ou des champs facultatifs qui devraient logiquement être obligatoires. C’est intentionnel — nous représentons quinze années d’évolution de l’API, durant lesquelles différents points de terminaison se sont développés à des moments différents, avec des conventions différentes.

Cette approche mesurée garantit que le code existant continue de fonctionner, que le nouveau code bénéficie d’indications adaptées et que les améliorations futures restent possibles. Nous pensons que les développeurs apprécient davantage l’honnêteté que l’idéalisme. Nos types décrivent fidèlement notre API, avec toutes ses particularités.

Migrer

Le passage de la v3 à la v4 nécessite quelques changements essentiels :

Liste de vérification pour une mise à niveau rapide

1. Passez à transloadit@^4.0.0 et assurez-vous d’utiliser Node.js 20 ou une version ultérieure
2. Remplacez les imports par défaut par des imports nommés
3. Supprimez les appels CommonJS à require (utilisez des imports dynamiques à la place)
4. Activez TypeScript ou ajoutez des annotations de types JSDoc pour améliorer l’assistance de l’éditeur
5. Adaptez la gestion des erreurs si vous utilisez des classes d’erreur personnalisées
6. Exécutez vos tests d’intégration avec validateResponses activé pour détecter les problèmes de schéma inattendus. Si vous rencontrez des erreurs, veuillez nous les signaler et nous les corrigerons.

Validation des réponses (facultative)

Activez la validation des réponses de l’API à l’exécution pendant le développement :

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
})

Une expérience de développement améliorée

Le nouveau SDK s’intègre facilement aux flux de travail modernes :

• Prise en charge complète d’IntelliSense dans VS Code et d’autres IDE
• Commentaires JSDoc détaillés pour toutes les méthodes et tous les paramètres
• Source maps pour faciliter le débogage
• Compatibilité avec la vérification stricte des valeurs nulles

Commencer

Installez le nouveau SDK :

npm install transloadit@^4.0.0

Créez un client et commencez à développer :

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',
      },
    },
  },
})

Quelle est la suite ?

Cette version v4 marque seulement le début de notre parcours avec TypeScript. À mesure que nous affinons notre API et nos schémas, vous bénéficierez de types encore plus précis, d’une meilleure documentation générée à partir des définitions de types, de messages d’erreur améliorés et d’améliorations progressives des schémas qui préservent la compatibilité.

Essayer dès aujourd’hui

Le SDK Node v4 est désormais disponible sur npm⁠ et GitHub⁠. Consultez le guide de migration⁠ pour obtenir des instructions détaillées sur la mise à niveau, et faites-nous part de vos impressions !

Vous souhaitez commencer ? Créez un compte gratuit et découvrez par vous-même le nouveau SDK reposant sur TypeScript.

Mise à jour du 2 févr. 2026 : nous proposons désormais aussi @transloadit/zod/v3, @transloadit/zod/v4, @transloadit/types si vous avez besoin de nos schémas ou de nos types sans inclure l’intégralité du SDK Node.js. Par ailleurs, le SDK est renommé @transloadit/node, tandis que transloadit restera disponible comme copie de celui-ci pour assurer la rétrocompatibilité.