Zuletzt aktualisiert: 20. September 2025

Node SDK v4: TypeScript-first mit umfassender Robot-Unterstützung

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Heute veröffentlichen wir Version 4 unseres Node.js-SDK, die größte Überarbeitung des Pakets seit seiner ersten Veröffentlichung. Sie können sich ab sofort auf umfassende TypeScript-Abdeckung, vollständige Robot-Definitionen mit Autovervollständigung, strukturierte Fehlerbehandlung und modernes Tooling verlassen – und das alles unter Berücksichtigung der fünfzehnjährigen Entwicklung einer API, die gemeinsam mit dem Node-Ökosystem gewachsen ist.

Was ist neu in v4

Das Node SDK v4 ist eine vollständige Neuimplementierung in TypeScript mit diesen wesentlichen Verbesserungen:

TypeScript-First-Design

Jeder Robot, jeder Parameter und jede Antwort ist jetzt vollständig typisiert. Beim Schreiben von Assembly Instructions schlägt Ihre IDE während der Eingabe die passenden Robots, Parameter und Rückgabewerte vor:

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

Assembly Instructions werden gegen umfangreiche Typen validiert, sodass Konfigurations- oder Abwärtskompatibilitätsprobleme früh während der lokalen Entwicklung auffallen statt mitten im Deployment.

Moderne JavaScript-Umgebung

Das SDK ist jetzt reines ESM, zielt auf Node.js 20+ ab und verwendet durchgängig benannte Exporte:

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

Verwenden Sie in CommonJS-Projekten dynamische Importe:

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

Verbesserte Fehlerbehandlung

Unsere Fehler enthalten jetzt aussagekräftige Stack Traces mit mehr Kontext für einfacheres Debugging.

Smart-CDN-URL-Helfer

Erzeugen Sie signierte Smart-CDN-URLs direkt aus dem SDK:

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

Unser Ansatz für die nachträgliche Typisierung

Als wir TypeScript zu einer API hinzugefügt haben, die über fünfzehn Jahre hinweg organisch gewachsen ist, standen wir vor einer interessanten Herausforderung. Unsere API entstand in den frühen Tagen von Node.js, als JavaScript deutlich freizügiger war – zu einer Zeit, in der dynamische Typisierung die Norm war.

Statt idealisierte Typdefinitionen zu schaffen, die bestehende Integrationen brechen würden, haben wir uns für einen pragmatischen Ansatz entschieden:

Abbilden, was existiert: Unsere Typen spiegeln die aktuelle API-Oberfläche exakt wider, auch wenn das bedeutet, weniger perfekte Muster zu akzeptieren.
Alles testen: Jede Typdefinition durchläuft unser Test-Harness, um sicherzustellen, dass sie dem tatsächlichen API-Verhalten entspricht.
Schrittweise zu mehr Eleganz: Mit exakten Typen als Fundament können wir sowohl die Schemas als auch die API selbst nach und nach verfeinern – und dabei stets die Abwärtskompatibilität sicherstellen.
Kompatibilität wahren: Wo die API Eigenheiten hat, dokumentieren wir sie, statt sofortige Änderungen zu erzwingen.

Dieser Ansatz bedeutet, dass unsere Typen anfangs möglicherweise keinen Schönheitswettbewerb gewinnen. Vielleicht sehen Sie Unions, wo Sie einen einzelnen Typ erwarten würden, oder optionale Felder, die logisch betrachtet Pflichtfelder sein sollten. Das ist Absicht – wir bilden fünfzehn Jahre API-Entwicklung ab, in denen verschiedene Endpunkte zu unterschiedlichen Zeiten und mit unterschiedlichen Konventionen gewachsen sind.

Mit diesem besonnenen Vorgehen stellen wir sicher, dass bestehender Code weiter funktioniert, neuer Code sinnvoll angeleitet wird und künftige Verbesserungen möglich bleiben. Wir glauben, dass Entwicklerinnen und Entwickler Ehrlichkeit mehr schätzen als Idealismus. Unsere Typen sagen die Wahrheit über unsere API, mit allen Eigenheiten.

Migrationsleitfaden

Der Umstieg von v3 auf v4 erfordert einige wesentliche Änderungen:

Kurze Upgrade-Checkliste

Aktualisieren Sie auf transloadit@^4.0.0 und stellen Sie sicher, dass Sie Node.js 20 oder neuer verwenden
Ersetzen Sie Default-Importe durch benannte Importe
Entfernen Sie CommonJS-Aufrufe von require (verwenden Sie stattdessen dynamische Importe)
Aktivieren Sie TypeScript oder ergänzen Sie JSDoc-Typisierungen für bessere Editor-Unterstützung
Passen Sie die Fehlerbehandlung an, wenn Sie eigene Fehlerklassen verwenden
Führen Sie Ihre Integrationstests aus, wobei validateResponses aktiviert ist, um Überraschungen beim Schema zu erkennen. Bitte melden Sie sich bei uns, falls Fehler auftreten, dann beheben wir das.

Validierung der Antworten (optional)

Aktivieren Sie während der Entwicklung die Laufzeitvalidierung von API-Antworten:

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

Verbesserungen beim Entwicklungserlebnis

Das neue SDK fügt sich nahtlos in moderne Workflows ein:

Vollständige IntelliSense-Unterstützung in VS Code und anderen IDEs
Detaillierte JSDoc-Kommentare für alle Methoden und Parameter
Source Maps für einfacheres Debugging
Kompatibilität mit striktem Null-Checking

Erste Schritte

Installieren Sie das neue SDK:

npm install transloadit@^4.0.0

Erstellen Sie einen Client und legen Sie los:

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

Wie geht es weiter?

Dieses v4-Release ist erst der Anfang unserer TypeScript-Reise. Während wir unsere API und Schemas weiter verfeinern, erhalten Sie noch präzisere Typen, eine bessere Dokumentation, die aus den Typdefinitionen generiert wird, verbesserte Fehlermeldungen und schrittweise Schema-Verfeinerungen, die die Kompatibilität wahren.

Testen Sie es noch heute

Das Node SDK v4 ist ab sofort auf npm und GitHub verfügbar. Werfen Sie einen Blick in den Migrationsleitfaden für ausführliche Upgrade-Anweisungen, und teilen Sie uns Ihre Meinung mit!

Bereit loszulegen? Registrieren Sie sich für ein kostenloses Konto und erleben Sie das neue TypeScript-basierte SDK selbst.

Update 2. Februar 2026: Wir bieten jetzt auch @transloadit/zod/v3, @transloadit/zod/v4, @transloadit/types an, falls Sie unsere Schemas oder Typen ohne das vollständige Node.js-SDK benötigen. Außerdem wurde es in @transloadit/node umbenannt, während transloadit als Klon davon aus Gründen der Abwärtskompatibilität weiterhin verfügbar bleibt.