File uploads

Direct-to-storage uploads, validation, previews. The patterns that don’t break under load.

File uploads should never go through your application’s request handler — direct-to-storage from the browser saves bandwidth, latency, and cost.

The standard pattern

1. Client requests an upload URL

   Mutation: generateUploadUrl() returns a one-time URL.

2. Client uploads bytes directly

   fetch(url, { method: "POST", body: file }).

3. Client gets back a storage ID

   Records the ID in the relevant row via a separate mutation.

4. Server serves the file

   Via the storage URL when needed.

See Convex file storage for the code.

Validation

Validate on the client (UX) AND on the server (security):

// Client (UX)
function validateFile(file: File) {
  if (file.size > 10 * 1024 * 1024) throw new Error("File too large (max 10 MB)");
  if (!["image/png", "image/jpeg"].includes(file.type)) throw new Error("Wrong type");
}

// Server (security) — in the mutation that records the storage ID
const blob = await ctx.storage.get(storageId);
if (blob.size > 10 * 1024 * 1024) throw new Error("File too large");
// Inspect bytes for actual file type if security matters

Don’t trust client-side checks alone. A malicious user can bypass them.

Previews

For images, generate a thumbnail at upload:

// In a Convex action triggered after upload:
const blob = await ctx.storage.get(originalId);
const thumbnail = await resize(blob, 200, 200);
const thumbId = await ctx.storage.store(thumbnail);
await ctx.db.patch(rowId, { thumbStorageId: thumbId });

Use Cloudinary if you need on-the-fly transforms; see Cloudinary integration.

Multiple files

For multi-file uploads (drag-and-drop a folder), upload in parallel with concurrency control:

async function uploadMany(files: File[]) {
  const queue = [...files];
  const concurrent = 3;
  const inflight: Promise<any>[] = [];

  while (queue.length || inflight.length) {
    while (inflight.length < concurrent && queue.length) {
      inflight.push(uploadOne(queue.shift()!));
    }
    await Promise.race(inflight);
  }
}

Limits

• Convex max per file: 100 MB by default.
• Larger files: use AWS S3 integration for multipart uploads.

Related

File uploads recipe

Worked walkthrough.

Convex file storage

Reference.

Cloudinary

Image transformations.