Convex
@transloadit/convex は、Transloadit をネイティブのように使える Convex コンポーネントです。サーバー側でアップロードオプションに署名し、Webhook を検証して、結果を Convex に保存します。これにより、UI をリアルタイムで更新できます。
インストール
npm i @transloadit/convex @uppy/core @uppy/transloadit
セットアップ
- コンポーネントを登録します。
// 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
- アプリの Convex 認証を設定します。サーバーの認証情報と、このアップロードフローの試用を許可する単一ユーザーの
tokenIdentifierを設定します。この識別子はブラウザーからの入力ではなく、信頼できる認証済みのサーバーコンテキストからctx.auth.getUserIdentity()を使って取得します。
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'
- 認可を行う署名アクションだけを公開します。コンポーネントの
makeTransloaditAPIラッパーは、アプリの認可処理を追加しません。この例はクライアントのパラメーターを受け取らず、以下のリサイズ処理だけに署名します。想定するアップロードは一つで、有効期限は五分です。
// 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'),
})
},
})
複数ユーザー向けのアプリでは、署名前に行う単一ユーザーの許可リストによる判定を、独自のメンバーシップとアップロード割り当て量の確認に置き換えてください。許可する処理設定はサーバー側で保持してください。結果のクエリと Webhook の受信処理には、それぞれアクセス制御が必要です。コンポーネントのバックエンドと Webhook のドキュメントを参照してください。
Uppy クライアント
アプリの認証済み ConvexClient をこのファクトリーに渡します。アップロード前に、利用する認証プロバイダーに合わせてクライアントの
setAuth() を設定します。コールバックはそのクライアント経由でアクションを呼び出し、その { params, signature, fields } の結果を Uppy に直接返します。
// 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, {}),
})
}
返された Uppy インスタンスをファイルピッカーと組み合わせて使い、uppy.upload() を呼び出します。ピッカーの制限はユーザーのファイル選択を補助するものです。認可と、許可された処理ジョブへの制限は、サーバーアクションが適用します。UI との統合については、Uppy ガイドに従ってください。
デモアプリ
convex-demo.transload.it で結婚式のギャラリーのエンドツーエンドのデモを試せます。完全なソースコードは GitHub リポジトリで確認できます。