Transloadit's Flutter SDK beta: cross-platform app support

Joseph Grabski

Content Lead · Rochester, United Kingdom · Show bio

In September 2022, we welcomed a Transloadit SDK for the cross-platform development framework Flutter. Version 0.2.0 provided wrappers for Transloadit API operations and resumable file uploads using the tus protocol. We introduced it as a beta, invited users to test it and report bugs, and did not consider it production ready.

The package is listed on pub.dev⁠.

Security update, September 2026: The original example placed an Auth Secret in the Flutter client. Do not distribute that secret in a mobile, desktop, or web app, or retrieve it into the app from remote configuration. The executable walkthrough has been replaced with the historical workflow and the package’s specific limitations below. Keeping the secret on a trusted backend is required; disguising it in an app does not make it private.

Installation

The release discussed here was 0.2.0. The package registry lists 0.2.1 as the latest published version at this update; it does not contain the 1.0.0 release previously shown in this article’s dependency example. The published 0.2.1 package declares the Dart SDK constraint >=2.12.0 <3.0.0 and a dependency on the Flutter SDK. It cannot be added unchanged to a project using Dart 3.

The library’s import path is package:transloadit/transloadit.dart. These details identify the historical package; they are not a recommendation to downgrade a current Flutter project. See the published package metadata⁠ when investigating an existing integration.

Using the SDK

The published client class is TransloaditClient, rather than the Transloadit class used in the original example. The client groups operations such as creating Assemblies, retrieving their status, and managing Templates so callers do not have to construct each HTTP request manually.

However, the 0.2.1 constructor requires an authSecret, and its request implementation signs parameters locally. It offers no public callback for server-generated signatures. Simply removing the secret from the constructor, passing an empty string, or adding a backend URL does not turn this package into a safe mobile signing integration. This limitation also applies to the 0.2.0 workflow described in the announcement.

A production integration needs a different request path: your backend must authenticate the user, authorize the upload, and control the processing instructions, destinations, limits, and expiry. It can create the Assembly itself or provide approved, short-lived parameters and a signature to a client capable of submitting them unchanged. Consult our Signature Authentication guide and Assembly creation API for that protocol. This is an architectural alternative, not a feature supplied by this Flutter package.

Creating an Assembly

The original walkthrough resized a local image to 400 pixels wide. Its sequence remains useful for understanding how the SDK was organized:

1. Call the client’s newAssembly method to obtain a TransloaditAssembly. This collects the files and Steps before the request is submitted.
2. Attach the sample image, cat.jpg, with addFile. The published package accepts a File and wraps its path in an XFile for the tus client.
3. Add a Step named resize, using the /image/resize Robot and a width of 400. This is the processing instruction for the image, separate from transferring its bytes.
4. Submit with createAssembly. The package first creates the Assembly and uses its tus upload URL to transfer files.
5. Use onProgress for transfer progress and onComplete for a completed file upload. In this workflow, upload completion is separate from processing completion; an upload callback alone does not establish that the resized image is ready.
6. Read the returned TransloaditResponse through response.data['ok'], rather than indexing the response object itself. ASSEMBLY_COMPLETED denotes successful processing. The package can also return a canceled or aborted Assembly, and errors need their own handling.

These API details explain the beta’s workflow without presenting the unsafe client-side signing path as a current upload recipe. A replacement must preserve the distinction between transfer progress and processing results while keeping authorization and secrets on the backend.

What next?

The announcement originally pointed to our Flutter recipe-app series as a larger example. That historical walkthrough also distributed credentials through remote configuration, so it should not be followed as a secure implementation guide. Start with the authentication and Assembly references above when designing a new integration.

For the beta’s implementation history and issue tracker, visit the Flutter SDK repository⁠. The invitation to contribute remains: a client integration that accepts authorized server-generated parameters would need its own implementation and verification before we could recommend it here.