File storage

Upload files directly to Convex from the client. Get a storage ID; serve via Convex’s CDN.

The full reference for Convex file storage. See Features → file storage for the executive overview.

Server side

convex/files.ts

import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const generateUploadUrl = mutation({
  args: {},
  handler: async (ctx) => await ctx.storage.generateUploadUrl(),
});

export const setAvatar = mutation({
  args: { storageId: v.id("_storage") },
  handler: async (ctx, { storageId }) => {
    const u = await ctx.auth.getUserIdentity();
    if (!u) throw new Error("Not signed in");
    await ctx.db.patch(u.subject as Id<"users">, { avatarStorageId: storageId });
  },
});

Client side

const generateUrl = useMutation(api.files.generateUploadUrl);
const setAvatar   = useMutation(api.files.setAvatar);

async function upload(file: File) {
  const url           = await generateUrl();
  const result        = await fetch(url, { method: "POST", body: file });
  const { storageId } = await result.json();
  await setAvatar({ storageId });
}

Serving

const url = await ctx.storage.getUrl(storageId);
// returns a signed CDN URL

For long-lived public URLs (e.g., user avatars in <img> tags), serve via the URL — Convex handles CDN caching automatically.

Deleting

await ctx.storage.delete(storageId);

Limits

• 100 MB max per file by default.
• Storage cap depends on plan (see Usage limits).

Related

File uploads recipe

Worked example.

Cloudinary

Advanced image transformations.

AWS S3

For files >100 MB.