Last updated: September 18, 2024
# Launching new Node.js SDK v3: enhanced & user-friendly
**Mikael Finstad**
Developer · Norway · Show bio
[](https://github.com/mifi)
It has been almost seven years since we[first announced](/blog/2014/06/releasing-our-official-nodejs-sdk.md) our Node.js SDK. Since then, the SDK has drastically evolved, but so has the JavaScript language as a whole. These days, developers love the simplicity of the new features that modern-day JavaScript brings to the table, such as Promises or the `await` and `async` functions. To keep up with standards, we have rewritten the SDK to use those new features by default. With our latest rebuild, it meant that we needed to release a new major version with breaking changes, but we hope you agree it was worth it! You can still use callbacks, but you would need to[callbackify](https://nodejs.org/api/util.html#util%5Futil%5Fcallbackify%5Foriginal) the methods yourself.
## New features
* New Promise API that is easier to use
* Allows uploading `Streams`, `strings` and more
* TypeScript definitions
* Improved error handling and retry logic
* Easier to debug and read internal async code
* Numerous [bugfixes and improvements](https://github.com/transloadit/node-sdk/pull/87)
Because this release contains breaking API changes, we have taken the opportunity to also do some major refactoring and stabilization to our SDK. We tried to keep the API similar to the previous version, but there are a few changes you need to be aware of.
## Breaking changes
* All previous callback-accepting methods now return a promise and do not accept a callback.
* Requires Node v10 or newer.
* `replayAssembly(opts)` changed to `replayAssembly(assemblyId, params)` (previously `assemblyId`was a key inside `opts`):
```diff
-replayAssembly(opts, callback)
+await replayAssembly(assemblyId, params)
```
* `replayAssemblyNotification(opts)` changed to `replayAssemblyNotification(assemblyId, params)`(previously `assemblyId` was a key inside `opts`):
```diff
-replayAssemblyNotification(opts, callback)
+await replayAssemblyNotification(assemblyId, params)
```
* `deleteAssembly` renamed to `cancelAssembly` to reflect the underlying API's terminology.
* Removed the undocumented `fields` option (directly under `createAssembly(opts)`). Please use the`fields` key inside `params` instead.
* Changed `createAssembly` progress callbacks:
```javascript
// Before:
createAssembly({
params: { ... },
fields: { field1: 'val' },
}, callback, progressCb)
// Now:
await createAssembly({
params: {
fields: { field1: 'val' },
},
onUploadProgress,
onAssemblyProgress,
})
```
Also, view the [readme](https://github.com/transloadit/node-sdk#readme).
* Increase default request timeout from `5` to `60` seconds.
* Now returns from `waitForCompletion` with the Assembly result instead of throwing an unknown error if `result.ok` is `ASSEMBLY_CANCELED` or `REQUEST_ABORTED`.
* Replaced `constructor` options `useSsl` and `service` with `endpoint`:
```javascript
// Before:
useSsl: true,
service: 'api2.transloadit.com'
// Now:
endpoint: 'https://api2.transloadit.com'
```
### Declarative `createAssembly`
`addFile` and `addStream` have been removed and are instead part of `createAssembly`:
```javascript
// Before:
transloadit.addFile('file1', '/path/to/file')
...
transloadit.createAssembly({ ... })
// Now:
transloadit.createAssembly({
files: {
file1: '/path/to/file',
...
},
...
})
```
```javascript
// Before:
transloadit.addStream('file2', process.data.stdin)
...
transloadit.createAssembly({ ... })
// Now:
transloadit.createAssembly({
uploads: {
file2: process.data.stdin,
...
},
...
})
```
### Auto retry logic
* `RATE_LIMIT_REACHED` now only automatically retries **five times**. The previous retry logic was overly aggressive: it used to retry on almost all errors, even unrecoverable ones, e.g.,`INVALID_FILE_META_DATA`.
* Will **no longer** automatically retry if `assembly_url == null` or `assembly_ssl_url == null`. Will instead throw a `Transloadit.InconsistentResponseError`.
### Errors
Errors thrown by the SDK have changed:
* When an unsuccessful HTTP response code is received, the error will now be a Transloadit.HTTPError object (used to be an ordinary Error object) with an additional transloaditErrorCode property (when relevant).
* Error messages have been improved.
* `Error` property `error` has been renamed to `transloaditErrorCode`.
* `Error` property `assembly_id` has been renamed to `assemblyId`.
* All other properties from the Transloadit JSON response are **no longer added directly to the`Error` object** but can instead be found in `HTTPError.response?.body`, e.g.,`catch (err) { err.response?.body?.assembly_id }`. Note that `err.response` will be `undefined`for non-server errors.
* Will now also await `ASSEMBLY_REPLAYING` status in `waitForCompletion`.
* Assemblies with an error status (`assembly.error`, but return HTTP 200) will also result in an error thrown when calling `replayAssembly` to make it consistent with`createAssembly`.
* When `result.ok` happens to be undefined, an `Unkown error` for createTemplate and editTemplate is no longer thrown.
* HTTP 404 responses from the server **now throw** a `Transloadit.HTTPError` (previously 404 gave a successful result).
## That's all folks!
Check out the following [documentation](https://github.com/transloadit/node-sdk#readme) and[examples](https://github.com/transloadit/node-sdk/tree/master/examples) to get up and running with our new and improved Node.js SDK v3! We hope you'll be able to put this announcement to good use, and we can't wait to see how it helps your projects. And as always, if you have any feedback,[let us know!](mailto:support@transloadit.com)
[#integrations](/blog/tags/integrations.md)[#node-sdk](/blog/tags/node-sdk.md)[#api](/blog/tags/api.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