Convex

@transloadit/convex ist eine Convex-Komponente, mit der sich Transloadit nativ anfühlt. Sie signiert Upload-Optionen serverseitig, verifiziert Webhooks und speichert Ergebnisse in Convex, damit sich Ihre Benutzeroberfläche in Echtzeit aktualisieren kann.

Installation

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

Einrichtung

Registrieren Sie die Komponente:

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

Richten Sie die Convex-Authentifizierung für Ihre App ein. Legen Sie die Zugangsdaten für den Server sowie die Kennung tokenIdentifier des einzigen Benutzers fest, der diesen Upload-Ablauf ausprobieren darf. Rufen Sie diese Kennung mithilfe von ctx.auth.getUserIdentity() aus einem vertrauenswürdigen, authentifizierten Serverkontext ab, nicht aus Browsereingaben:

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'

Stellen Sie nur eine durch Autorisierung geschützte Signieraktion bereit. Die Wrapper makeTransloaditAPI der Komponente fügen keine Autorisierung auf Anwendungsebene hinzu. Dieses Beispiel akzeptiert keine Client-Parameter und signiert nur den unten gezeigten Job zur Größenänderung, für einen erwarteten Upload und mit einer Gültigkeit von fünf Minuten:

// 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'),
    })
  },
})

Ersetzen Sie bei einer App für mehrere Benutzer die Freigabeliste für einen einzelnen Benutzer durch eigene Prüfungen der Mitgliedschaft und des Upload-Kontingents, die vor dem Signieren erfolgen. Belassen Sie die zulässigen Instructions auf dem Server. Ergebnisabfragen und die Annahme von Webhooks benötigen eigene Zugriffskontrollen; siehe die Backend- und Webhook-Dokumentation der Komponente.

Uppy-Client

Übergeben Sie dieser Factory den authentifizierten Client ConvexClient Ihrer App. Konfigurieren Sie vor dem Upload setAuth() des Clients mit Ihrem Authentifizierungsanbieter. Der Callback ruft die Aktion über diesen Client auf und gibt deren Ergebnis { params, signature, fields } direkt an Uppy zurück:

// 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, {}),
  })
}

Verwenden Sie die zurückgegebene Uppy-Instanz mit Ihrer Dateiauswahl und rufen Sie anschließend uppy.upload() auf. Die Einschränkungen der Dateiauswahl helfen dem Benutzer, eine Datei auszuwählen; die Serveraktion erzwingt die Autorisierung und die Beschränkung auf den zulässigen Verarbeitungsjob. Folgen Sie für UI-Integrationen der Uppy-Anleitung.

Demo-App

Sehen Sie sich die vollständige Hochzeitsgalerie-Demo unter convex-demo.transload.it und den vollständigen Quellcode im GitHub-Repository an.