Skip to main content

File Storage

Example: File Storage in Convex Chat

Convex supports uploading and serving files, such as images, via Convex storage.

Each file is stored keyed by a specific string storage ID. You can save the storage IDs within your documents


Uploading Files

Uploading files require three steps:

  1. Generate an upload URL using a mutation that calls storage.generateUploadUrl().
  2. POST a file to that URL and receive a storage ID.
  3. Save the storage ID into your data model via a mutation.

As an example, these might appear in a form submission handler.

// Step 1: Get a short-lived upload URL
const postUrl = await generateUploadUrl();
// Step 2: POST the file to the URL
const result = await fetch(postUrl, {
method: "POST",
headers: { "Content-Type": selectedImage.type },
body: selectedImage,
const { storageId } = await result.json();
// Step 3: Save the newly allocated storage id to the messages table
await sendImage(storageId, name);
// Generate a short-lived upload URL.
export const generateUploadUrl = mutation(async ({ storage }) => {
return await storage.generateUploadUrl();
// Save the storage ID within a message.
export const sendImage = mutation(async ({ db }, storageId, author) => {
const message = { body: storageId, author, format: "image" };
await db.insert("messages", message);

Fetching Files

Download URLs can be generated from storage IDs inside of queries and mutations.

export default query(async ({ db, storage }) => {
const messages = await db.query("messages").collect();
for (const message of messages) {
if (message.format == "image") {
message.url = await storage.getUrl(message.body);
return messages;

Rendering Images

Download URLs can be used in img tags to render images.

function Image({ message }) {
return <img src={message.url} height="300px" width="auto" />;

Deleting Files

Files can be deleted inside of mutations using storage.delete(). The delete method returns true if successful and false if the storage id is not found.

export const deleteById = mutation(async ({ storage }, storageId) => {
return await storage.delete(storageId);