Secure file uploads in Next.js with Uppy and signed Transloadit Templates

Separate application authorization from upload execution

The browser is an untrusted caller even when the interface is part of your Next.js application. A Client Component may contain the public Auth Key and a Template ID, but it must never contain the Workspace Auth Secret, raw storage credentials, or authority to choose arbitrary processing Steps. Put the Auth Secret behind a Route Handler and make that endpoint decide whether the current application user may start this exact upload.

That decision is separate from Transloadit request integrity. A valid signature proves that your server approved the serialized Assembly parameters for a limited period; it does not prove that the person asking your server for a signature owns a project, remains within quota, passed a CSRF check, or may publish the result. The application authorization adapter must enforce those rules before signing. The saved Template then constrains what Transloadit will execute.

Lock the Template before exposing the upload form

Create the processing workflow as a saved Template. Set allow_steps_override to false so a browser cannot submit replacement Steps alongside its template_id. Enable “Require a valid signature” on this Template, or require correct signatures for the whole Workspace. These are distinct controls: the locked Template fixes the processing graph, while signature enforcement rejects altered, expired, or otherwise invalid signed parameters. Your application still decides which user may receive those parameters.

Repeat inexpensive interface restrictions at the processing boundary. The example caps every file at 50 MiB, caps an Assembly at five files, and uses /file/filter against detected MIME metadata rather than trusting the filename or browser declaration. Adapt the exact allowlist to the product. Add verification, malware scanning, quarantine, or human review when the content risk requires them; no single MIME check makes arbitrary user content safe.

The user_uploads value names Template Credentials stored in the Workspace. Give that external principal only the storage operations, bucket, and paths required by this workflow. The browser neither receives nor signs the underlying access key. Credential rotation can then happen independently of the Next.js bundle, but it must be coordinated because every Template that references the record is affected.

{
  "allow_steps_override": false,
  "auth": {
    "max_number_of_files": 5,
    "max_size": 52428800
  },
  "notify_url": "https://app.example.com/api/transloadit-notifications",
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^(image/jpeg|image/png|image/webp)$"]
      ],
      "error_on_decline": true,
      "error_msg": "Only JPEG, PNG, and WebP images are accepted"
    },
    "stored": {
      "use": "accepted_images",
      "robot": "/s3/store",
      "credentials": "user_uploads"
    }
  }
}

Sign one short-lived request in a server-only module

Keep server configuration in environment variables without a NEXT_PUBLIC_ prefix and import server-only at the top of the signing module. Next.js will fail the build if client code imports that module. The marker is a useful guardrail, not a secret manager: production access policies, log redaction, preview-environment isolation, and credential rotation still matter.

The Node SDK adds the configured Auth Key, serializes the parameters, and returns that exact params string with its signature. Return both values unchanged. Parsing the string, adding a field, or serializing it again in a different order after signing produces a different payload and should be rejected. The example sets a five-minute expiry because Uppy requests options immediately before Assembly creation and adds a fresh nonce for each authorization.

Select the Template on the server. Do not accept template_id, steps, notify_url, export credentials, or unbounded transformation values from the request body and sign them blindly. If the product genuinely offers several upload workflows, map a small application-level operation such as avatar or product-gallery to an allowlisted Template and limits after checking the user’s permission.

import 'server-only'

import { randomUUID } from 'node:crypto'

import { Transloadit } from 'transloadit'

export interface AssemblyOptions {
  params: string
  signature: string
}

type TransloaditEnvironmentName =
  | 'TRANSLOADIT_KEY'
  | 'TRANSLOADIT_SECRET'
  | 'TRANSLOADIT_TEMPLATE_ID'

function readServerEnvironment(name: TransloaditEnvironmentName): string {
  const value = process.env[name]
  if (value == null || value === '') {
    throw new Error('Missing Transloadit server configuration')
  }

  return value
}

const templateId = readServerEnvironment('TRANSLOADIT_TEMPLATE_ID')
const transloadit = new Transloadit({
  authKey: readServerEnvironment('TRANSLOADIT_KEY'),
  authSecret: readServerEnvironment('TRANSLOADIT_SECRET'),
})

export function createAssemblyOptions(): AssemblyOptions {
  const requestParameters = {
    auth: {
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      nonce: randomUUID(),
    },
    template_id: templateId,
  }

  return transloadit.calcSignature(requestParameters)
}

Protect the App Router signing endpoint

A Route Handler is reachable like any other HTTP endpoint. The authorizeUpload function in the sample is deliberately application-specific: connect it to the project’s existing session library, resource ownership checks, CSRF strategy, and shared rate limiter. Return denial before signature generation. For multi-tenant applications, key limits by both tenant and user, and check the tenant that will own the eventual asset.

The route accepts no arbitrary Assembly parameters and marks the successful response no-store. Its public failure is intentionally generic. Log an internal request or trace identifier, decision category, and actor ID on the server, but do not return stack traces, account identifiers, third-party response bodies, or credential details to the browser. Let unexpected failures use the application’s centralized sanitized error handling rather than wrapping every call in a noisy catch block.

Rate limiting the signature route controls Assembly creation, but it does not replace account bill limits, Template file limits, or application quotas. Apply all three. A signature is a short-lived capability: anyone who obtains the complete signed payload can attempt to submit it while it remains valid, so send it only over HTTPS and avoid analytics, browser storage, URLs, and logs that retain it.

import type { NextRequest } from 'next/server'

import { NextResponse } from 'next/server'

import { authorizeUpload } from '../../../server/upload-authorization'
import {
  type AssemblyOptions,
  createAssemblyOptions,
} from '../../../server/transloadit-options'

interface ErrorResponse {
  error: string
}

export async function POST(
  request: NextRequest,
): Promise<NextResponse<AssemblyOptions | ErrorResponse>> {
  const permission = await authorizeUpload(request)
  if (!permission.allowed) {
    return NextResponse.json({ error: 'Upload not allowed' }, { status: 403 })
  }

  return NextResponse.json(createAssemblyOptions(), {
    headers: { 'Cache-Control': 'no-store' },
  })
}

Mount Uppy once inside a Client Component

Uppy needs browser APIs, so the uploader lives behind a use client boundary. Create the Uppy instance once with a lazy state initializer. Recreating it during render discards selected files and breaks lifecycle ownership. This component destroys the instance when it owns the complete upload lifetime; if uploads must survive navigation between routes, lift the instance to a longer-lived client provider and destroy it when that provider ends.

The asynchronous assemblyOptions function calls the protected route as Uppy prepares the upload. It checks response.ok, safely handles malformed JSON, validates the response shape, and exposes only a stable user-facing authorization error. Uppy’s Dashboard supplies selection, progress, cancellation, and error UI, while the Transloadit plugin creates the Assembly and sends files through resumable upload infrastructure. The bounded retry schedule helps temporary failures without retrying forever.

Those retries operate while this Uppy instance remains alive. They do not make the shown component recover selected files and Assembly state after a page reload. If reload recovery is a product requirement, configure and test Golden Retriever or another documented persistence design with the Transloadit plugin; do not infer it from tus or retryDelays alone.

The browser limits mirror the Template for fast feedback, but they are not the security boundary. A caller can bypass the component, and file metadata can be false. Keep the authoritative file count, byte size, detected-content checks, and export policy in the locked Template. Also decide whether canceling the browser should cancel only transfer, the Assembly, or the application asset record, then test that decision instead of assuming all three states are identical.

'use client'

import Uppy from '@uppy/core'
import Dashboard from '@uppy/react/dashboard'
import Transloadit from '@uppy/transloadit'
import { type ReactNode, useEffect, useState } from 'react'
import { z } from 'zod'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

const assemblyOptionsSchema = z.object({
  params: z.string().min(1),
  signature: z.string().regex(/^(sha1|sha256|sha384):[0-9a-f]+$/),
})

async function fetchAssemblyOptions(): Promise<z.infer<typeof assemblyOptionsSchema>> {
  const response = await fetch('/api/transloadit-params', {
    method: 'POST',
    headers: { Accept: 'application/json' },
  })

  if (!response.ok) {
    throw new Error('Could not authorize this upload. Try again.')
  }

  const responseBody: unknown = await response.json().catch(() => null)
  const parsedOptions = assemblyOptionsSchema.safeParse(responseBody)
  if (!parsedOptions.success) {
    throw new Error('Could not authorize this upload. Try again.')
  }

  return parsedOptions.data
}

function createUppy(): Uppy {
  return new Uppy({
    restrictions: {
      allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
      maxFileSize: 50 * 1024 * 1024,
      maxNumberOfFiles: 5,
    },
  }).use(Transloadit, {
    assemblyOptions: fetchAssemblyOptions,
    retryDelays: [0, 1_000, 3_000, 5_000],
    waitForEncoding: false,
  })
}

export function UploadForm(): ReactNode {
  const [uppy] = useState(createUppy)

  useEffect(() => {
    return () => uppy.destroy()
  }, [uppy])

  return <Dashboard height={420} proudlyDisplayPoweredByUppy={false} uppy={uppy} />
}

Reconcile progress, retries, and completion

Transfer progress and processing progress answer different questions. With waitForEncoding: false, the interface can finish after bytes reach Transloadit while validation, transformation, and export continue. Listen for transloadit:assembly-created and associate the Assembly ID with a pending application record. A navigation can then interrupt browser observation without losing the identity needed for reconciliation.

Put a fixed notify_url in the server-owned Template for asynchronous completion. The notification handler must verify its signature using the Auth Secret associated with the Assembly’s Auth Key, validate the payload, match the Assembly ID to the expected pending record, and apply results idempotently before returning success. Notifications may be retried, so a duplicate must confirm the existing terminal state rather than create another asset or publication event.

Use waitForEncoding: true only for short workflows where the user should stay on the page and browser code genuinely needs final results. Even then, retain a server-side recovery path because tabs close and connections disappear. A scheduled reconciliation job can query nonterminal Assemblies whose notifications were missed. Separate retry policy by failure: resume network interruption, request new signed options when they expire before Assembly creation, and stop on a policy rejection until the user changes the file.

Test the controls as an attacker and as an interrupted user

Test the signing endpoint without a session, with the wrong tenant, with a missing or invalid CSRF token where applicable, above its rate limit, and after permission revocation. Confirm that no response or log contains the Auth Secret, Template Credentials, stack trace, or raw dependency error. Try replacing the template_id, adding steps, extending auth.expires, and submitting signed options after their expiry; signature or Template enforcement should reject the invalid request.

Exercise a permitted JPEG, a disallowed MIME type with an image extension, an oversized file, too many files, a zero-byte file, a connection loss at several offsets, browser reload, cancellation, expired authorization, duplicate notification, storage denial, and processing failure after upload. Confirm that reload behavior matches the persistence design instead of assuming automatic recovery. Verify accessible progress and error announcements with keyboard and assistive technology, then inspect temporary storage and application records for leaks or permanently pending states.

Monitor signature denials, rate-limit decisions, Assembly creation and failure rates, upload recovery, processing latency, notification age, storage errors, and pending-record age without logging protected payloads. Alert on sustained changes rather than individual user mistakes. Keep the Template ID and an application-managed workflow release in operational records because a saved Template can change over time.