<span aria-hidden="true" id="convex-"></span>

# Convex

[transloadit/convex](https://github.com/transloadit/convex)

`@transloadit/convex` is a Convex component that makes Transloadit feel native. It signs upload options server-side, verifies webhooks, and stores results in Convex so your UI can update in real time.

<span aria-hidden="true" id="install"></span>

## Install

```bash
npm i @transloadit/convex @uppy/core @uppy/transloadit

```

<span aria-hidden="true" id="setup"></span>

## 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

```

1. Configure [Convex authentication](https://docs.convex.dev/auth) for your app. Set the server credentials and the `tokenIdentifier` of the one user allowed to try this upload flow. Retrieve that identifier from a trusted, authenticated server context using [ctx.auth.getUserIdentity()](https://docs.convex.dev/auth/functions-auth), not from browser input:

```bash
npx convex env set TRANSLOADIT_KEY 'YOUR_AUTH_KEY'
npx convex env set TRANSLOADIT_SECRET 'YOUR_AUTH_SECRET'
npx convex env set TRANSLOADIT_UPLOADER_TOKEN_IDENTIFIER 'YOUR_APPROVED_TOKEN_IDENTIFIER'

```

1. Expose only an authorized signing action. The component’s `makeTransloaditAPI` wrappers do not add application authorization. This example accepts no client parameters and signs only the resize job below, for one expected upload, with a five-minute expiry:

```ts
// convex/transloadit.ts
import { Transloadit } from '@transloadit/convex'
import { ConvexError } from 'convex/values'
import { components } from './_generated/api'
import { action } from './_generated/server'

const transloadit = new Transloadit(components.transloadit)

export const createAssemblyOptions = action({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity()
    if (identity === null) {
      throw new ConvexError('Sign in to upload files.')
    }

    const allowedUploader = process.env.TRANSLOADIT_UPLOADER_TOKEN_IDENTIFIER
    if (!allowedUploader || identity.tokenIdentifier !== allowedUploader) {
      throw new ConvexError('Uploads are not enabled for this account.')
    }

    return transloadit.createAssemblyOptions(ctx, {
      steps: {
        resized: {
          use: ':original',
          robot: '/image/resize',
          width: 800,
        },
      },
      numExpectedUploadFiles: 1,
      // Whole-second UTC avoids ambiguity in API date parsing.
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z'),
    })
  },
})

```

For a multi-user app, replace the single-user allowlist with your own membership and upload-quota checks before signing. Keep the allowed Instructions on the server. Result queries and webhook ingestion need their own access controls; see the [component’s backend and webhook documentation](https://github.com/transloadit/convex#backend-api).

<span aria-hidden="true" id="uppy-client"></span>

## Uppy client

Pass your app’s authenticated `ConvexClient` to this factory. Configure the client’s [setAuth()](https://docs.convex.dev/api/classes/browser.ConvexClient#setauth) with your auth provider before uploading. The callback calls the action through that client and returns its `{ params, signature, fields }` result directly to Uppy:

```ts
// src/uploader.ts
import Uppy from '@uppy/core'
import Transloadit from '@uppy/transloadit'
import type { ConvexClient } from 'convex/browser'
import { api } from '../convex/_generated/api'

export function createUploader(convex: ConvexClient): Uppy {
  return new Uppy({
    restrictions: { maxNumberOfFiles: 1, allowedFileTypes: ['image/*'] },
  }).use(Transloadit, {
    waitForEncoding: true,
    assemblyOptions: () => convex.action(api.transloadit.createAssemblyOptions, {}),
  })
}

```

Use the returned Uppy instance with your file picker, then call `uppy.upload()`. The picker restrictions help the user select a file; authorization and the allowed processing job are enforced by the server action. Follow the [Uppy guide](/docs/sdks/uppy.md) for UI integrations.

<span aria-hidden="true" id="demo-app"></span>

## Demo app

See the end-to-end wedding gallery demo at [convex-demo.transload.it](https://convex-demo.transload.it/) and the full source in the [GitHub repo](https://github.com/transloadit/convex).
