Last updated: September 20, 2025
# Node SDK v4: TypeScript-first with comprehensive Robot support
**Kevin van Zonneveld**
Co-founder · Amsterdam, The Netherlands · Show bio
[](https://x.com/kvz)[](https://github.com/kvz)
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 Robotdefinitions with autocomplete, structured error handling, and modern tooling — all while respecting the fifteen-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:
```typescript
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:
```typescript
// Named exports replace the default export
import { Transloadit } from 'transloadit'
```
For CommonJS projects, use dynamic imports:
```javascript
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:
```typescript
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 fifteen 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. This is intentional — we're capturing fifteen years of API evolution, during which 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:
```typescript
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
})
```
### 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:
```bash
npm install transloadit@^4.0.0
```
Create a client and start building:
```typescript
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](https://www.npmjs.com/package/transloadit) and[GitHub](https://github.com/transloadit/node-sdk). Check out the[migration guide](https://github.com/transloadit/node-sdk/blob/main/MIGRATION.md) for detailed upgrade instructions, and let us know what you think!
Ready to get started? [Sign up for a free account](/c/signup/) and experience the new TypeScript-powered SDK for yourself.
**Update 2 Feb 2026:** we now also offer `@transloadit/zod/v3`, `@transloadit/zod/v4`,`@transloadit/types` in case you need our schemas or types without pulling in the full Node.js SDK. In addition, it is rebranded to `@transloadit/node`, while the `transloadit` will remain available as a clone of this, for backwards compatibility.
[#nodejs](/blog/tags/nodejs.md)[#sdks](/blog/tags/sdks.md)[#typescript](/blog/tags/typescript.md)[#developer-experience](/blog/tags/developer-experience.md)
### 👩💻 Join 20k+ developers
Sign up for our [monthly newsletter](/newsletters.md) to receive direct links to 3 exclusive tech — and 2 product updates. No less, no more.
Your email:
Get access
## File uploading and encoding. Made simple.
Transloadit streamlines file handling for developers, trusted by brands like Coursera and The New York Times. We’re known for a reliable API, top-notch support, and a strong commitment to open source, with projects like [Uppy](https://uppy.io) and [Tus](https://tus.io) setting standards in file processing.
[Sign up](/c/)[Book a Demo](https://survey.typeform.com/to/kRg47Xi5)
No credit card needed
Cancel anytime