# Transloadit

Upload and media processing

- Package: @bijectionhq/transloadit
- Category: Media
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/transloadit/tree/a26a7c41bee57e8ce8fef983dcf6b488b896766d
- Upstream: https://github.com/transloadit/convex/tree/44b4bbd85e3481cbd3524716318c61796967ff25
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/transloadit

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/transloadit.git
cd transloadit
git checkout a26a7c41bee57e8ce8fef983dcf6b488b896766d
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @transloadit/convex; check the Bijection adaptation separately.

This component provides a complete integration between Convex and Transloadit's media processing platform. It handles creating Assemblies with Templates or inline Steps, generates signed upload options for secure client-side uploads with Uppy, and persists Assembly status and results in Convex tables. The component includes webhook ingestion with signature verification and provides typed API wrappers for managing the entire media processing lifecycle.

### Use cases

- **Build media galleries** where users upload images/videos that need automatic resizing, format conversion, or thumbnail generation before storage
- **Process user-generated content** by creating secure upload flows that resize avatars, compress videos, or extract metadata without exposing API secrets to clients
- **Handle file transformations** in real-time applications where you need to track processing status and display results as they complete
- **Implement batch media processing** for applications that need to apply consistent transformations across multiple files with webhook-based status updates
- **Create secure upload workflows** using Uppy where authentication and processing parameters are generated server-side but uploads happen client-side

### How it works

The component follows a secure server-first pattern where Convex actions create signed `assemblyOptions` using `createAssembly` or `createAssemblyOptions`, keeping your Transloadit auth secret server-side. Clients use these options with Uppy and `@uppy/transloadit` to upload directly to Transloadit for processing.

Webhooks are handled through `handleWebhookRequest` which verifies signatures and can either process immediately or queue via `queueWebhook` for durable processing. The component maintains two tables: `assemblies` for tracking processing status and metadata, and `results` for storing individual output files grouped by `assemblyId` and `stepName`.

The main API is exposed through `makeTransloaditAPI` which provides functions like `refreshAssembly`, `getAssemblyStatus`, and `listResults` for building real-time UIs. You configure it by registering the component in `convex.config.ts` and setting `TRANSLOADIT_KEY` and `TRANSLOADIT_SECRET` environment variables.

### Upstream README

# Transloadit Convex Component

A Convex component for creating Transloadit Assemblies, signing Uppy uploads, and persisting status/results in Convex.

## Features

- Create Assemblies with Templates or inline Steps.
- Signed upload options for Uppy + `@uppy/transloadit`.
- Webhook ingestion with signature verification (direct or queued).
- Persist Assembly status + results in Convex tables.
- Typed API wrappers and helpers.

## Requirements

- Node.js 24+
- Yarn 4 (Corepack)

## Install

```bash
yarn add @transloadit/convex
```

## Setup

### 1) Register the component

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import transloadit from "@transloadit/convex/convex.config";

const app = defineApp();
app.use(transloadit);

export default app;
```

### 2) Set environment variables

```bash
npx convex env set TRANSLOADIT_KEY <your_auth_key>
npx convex env set TRANSLOADIT_SECRET <your_auth_secret>
```

## Golden path (secure by default)

1. **Server-only create**: a Convex action creates signed `assemblyOptions` (auth secret stays server-side).
2. **Client upload**: use Uppy + `@uppy/transloadit` with `assemblyOptions()`.
3. **Webhook ingestion**: verify the signature and `queueWebhook` for durable processing.
4. **Realtime UI**: query status/results and render the gallery.

## Backend API

```ts
// convex/transloadit.ts
import { makeTransloaditAPI } from "@transloadit/convex";
import { components } from "./_generated/api";

export const {
  createAssembly,
  createAssemblyOptions,
  handleWebhook,
  queueWebhook,
  refreshAssembly,
  getAssemblyStatus,
  listAssemblies,
  listResults,
  storeAssemblyMetadata,
} = makeTransloaditAPI(components.transloadit);
```

Note: pass `expires` in `createAssembly` when you need a custom expiry; otherwise the component defaults to 1 hour from now.

## Data model

The component stores Transloadit metadata in two tables:

```
assemblies 1 ──── * results
```

- `assemblies`: one row per Transloadit Assembly (status/ok, notify URL, uploads, raw payload, etc).
- `results`: one row per output file, grouped by `assemblyId` + `stepName` (a step can yield multiple rows). Each row includes normalized fields (name/size/mime/url), optional `resultId`, and the raw Transloadit output object.

Lifecycle:
1. `createAssembly` inserts the initial `assemblies` row.
2. `handleWebhook`, `queueWebhook`, or `refreshAssembly` upserts the assembly + replaces results.
3. `listResults` returns flattened step outputs for use in UIs.

## Webhook route

Transloadit sends webhooks as `multipart/form-data` with `transloadit` (JSON) and `signature` fields.

```ts
// convex/http.ts
import { httpRouter } from "convex/server";
import { handleWebhookRequest } from "@transloadit/convex";
import { api } from "./_generated/api";
import { httpAction } from "./_generated/server";

const http = httpRouter();

http.route({
  path: "/transloadit/webhook",
  method: "POST",
  handler: httpAction((ctx, request) =>
    handleWebhookRequest(request, {
      mode: "queue",
      runAction: (args) => ctx.runAction(api.transloadit.queueWebhook, args),
    }),
  ),
});

export default http;
```

## Client wrapper (optional)

Most integrations should use `makeTransloaditAPI` (above). If you prefer a class-based API
(similar to other Convex components), use `Transloadit`:

```ts
import { Transloadit } from "@transloadit/convex";
import { components } from "./_generated/api";

const transloadit = new Transloadit(components.transloadit, {
  authKey: process.env.TRANSLOADIT_KEY!,
  authSecret: process.env.TRANSLOADIT_SECRET!,
});
```

## Uppy client (React example)

```tsx
import Uppy from "@uppy/core";
import Transloadit from "@uppy/transloadit";
import { api } from "../convex/_generated/api";

const uppy = new Uppy().use(Transloadit, {
  waitForEncoding: true,
  assemblyOptions: async () => {
    const { assemblyOptions } = await runAction(
      api.wedding.createWeddingAssemblyOptions,
      { fileCount, guestName, uploadCode },
    );
    return assemblyOptions;
  },
});

await uppy.upload();
```
Note: `assemblyOptions()` is called once per batch, so pass per-file metadata via Uppy file meta
(e.g. `uppy.setFileMeta(fileId, {...})`) and use `fields` for shared values.

Migration note: the `@transloadit/convex/react` entrypoint has been removed; use Uppy +
`@uppy/transloadit` directly.

For status parsing and polling helpers, see `docs/advanced.md`.

## Example app (Next.js + Uppy wedding gallery)

The `example/` app is a wedding gallery where guests upload photos + short videos. It uses Uppy on
the client and Convex Auth (anonymous sign-in) to create assemblies securely. Uploads are stored via
Transloadit directly into Cloudflare R2.

Live demo: `https://convex-demo.transload.it`

For setup, deployment, and verification details, see `CONTRIBUTING.md`.