Today we're releasing version 4 of our Node.js SDK, the biggest rethink of the package since its initial launch. You can now rely on comprehensive TypeScript coverage, full Robot definitions with autocomplete, structured error handling, and modern tooling — all while respecting the 15-year journey of an API that has grown alongside the Node ecosystem.

What's new in v4

The Node SDK v4 represents a complete TypeScript rewrite with these major improvements:

TypeScript-first design

Every Robot, parameter, and response is now fully typed. When writing Assembly Instructions, your IDE suggests the correct Robots, parameters, and return values as you type:

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 are validated against rich types, catching configuration or backwards-compatibility issues early during local development instead of mid-deployment.

Modern JavaScript environment

The SDK is now pure ESM and targets Node.js 20+, using named exports throughout:

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

For CommonJS projects, use dynamic imports:

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

Improved error handling

Our errors now include rich stack traces with more context for easier debugging.

Smart CDN URL helper

Generate signed Smart CDN URLs directly from the SDK:

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

Our approach to type retrofitting

When adding TypeScript to an API that has evolved organically over 15 years, we faced an interesting challenge. Our API started in the early days of Node.js when JavaScript was far more permissive — a time when dynamic typing was the norm.

Rather than creating idealized type definitions that would break existing integrations, we chose a pragmatic approach:

  1. Model What Exists: Our types accurately reflect the current API surface, even when that means accepting less-than-perfect patterns.

  2. Test Everything: Each type definition goes through our test harness to ensure it matches actual API behavior.

  3. Iterate Towards Beauty: With accurate types as our foundation, we can gradually refine both the schemas and the API itself — always ensuring backward compatibility.

  4. Preserve Compatibility: Where the API has quirks, we document them rather than forcing immediate changes.

This approach means our types might not win beauty contests initially. You might see unions where you'd expect a single type, or optional fields that should logically be required. That's intentional — we're capturing 15 years of API evolution where different endpoints grew at different times with different conventions.

By taking this measured approach, we ensure that existing code keeps working, new code gets proper guidance, and future improvements remain possible. We believe developers appreciate honesty over idealism. Our types tell the truth about our API, quirks and all.

Migration guide

Moving from v3 to v4 requires a few key changes:

Quick upgrade checklist

  1. Update to transloadit@^4.0.0 and ensure you're on Node.js 20 or newer
  2. Swap default imports for named imports
  3. Remove CommonJS require calls (use dynamic imports instead)
  4. Enable TypeScript or add JSDoc typings for better editor support
  5. Update error handling if you use custom error classes
  6. Run your integration tests with validateResponses enabled to catch schema surprises. Please report back to us if you're getting any errors, and we'll get it fixed.

Response validation (optional)

Enable runtime validation of API responses during development:

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 still defaults to false
})

Development experience improvements

The new SDK integrates seamlessly with modern workflows:

  • Full IntelliSense support in VS Code and other IDEs
  • Detailed JSDoc comments for all methods and parameters
  • Source maps for easier debugging
  • Strict null checking compatibility

Getting started

Install the new SDK:

npm install transloadit@^4.0.0

Create a client and start building:

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

What's next

This v4 release is just the beginning of our TypeScript journey. As we continue refining our API and schemas, you'll see even more precise types, better documentation generated from type definitions, improved error messages, and gradual schema refinements that maintain compatibility.

Try it today

The Node SDK v4 is available now on npm and GitHub. Check out the migration guide for detailed upgrade instructions, and let us know what you think!

Ready to get started? Sign up for a free account and experience the new TypeScript-powered SDK for yourself.