Convex File Storage

Handle file uploads, storage, serving, and management in Convex applications with proper patterns for images, documents, and generated files.

Documentation Sources

Before implementing, do not assume; fetch the latest documentation:

• Primary: https://docs.convex.dev/file-storage

• Upload Files: https://docs.convex.dev/file-storage/upload-files

• Serve Files: https://docs.convex.dev/file-storage/serve-files

• For broader context: https://docs.convex.dev/llms.txt

Instructions

File Storage Overview

Convex provides built-in file storage with:

• Automatic URL generation for serving files

• Support for any file type (images, PDFs, videos, etc.)

• File metadata via the _storage system table

• Integration with mutations and actions

Generating Upload URLs

// convex/files.ts

import { mutation } from "./_generated/server";

import { v } from "convex/values";

export const generateUploadUrl = mutation({

  args: {},

  returns: v.string(),

  handler: async (ctx) => {

    return await ctx.storage.generateUploadUrl();

  },

});

Client-Side Upload

// React component

import { useMutation } from "convex/react";

import { api } from "../convex/_generated/api";

import { useState } from "react";

function FileUploader() {

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

  const saveFile = useMutation(api.files.saveFile);

  const [uploading, setUploading] = useState(false);

  const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {

    const file = e.target.files?.[0];

    if (!file) return;

    setUploading(true);

    try {

      // Step 1: Get upload URL

      const uploadUrl = await generateUploadUrl();

      // Step 2: Upload file to storage

      const result = await fetch(uploadUrl, {

        method: "POST",

        headers: { "Content-Type": file.type },

        body: file,

      });

      const { storageId } = await result.json();

      // Step 3: Save file reference to database

      await saveFile({

        storageId,

        fileName: file.name,

        fileType: file.type,

        fileSize: file.size,

      });

    } finally {

      setUploading(false);

    }

  };

  return (

    <div>

      <input

        type="file"

        onChange={handleUpload}

        disabled={uploading}

      />

      {uploading &#x26;&#x26; <p>Uploading...</p>}

    </div>

  );

}

Saving File References

// convex/files.ts

import { mutation, query } from "./_generated/server";

import { v } from "convex/values";

export const saveFile = mutation({

  args: {

    storageId: v.id("_storage"),

    fileName: v.string(),

    fileType: v.string(),

    fileSize: v.number(),

  },

  returns: v.id("files"),

  handler: async (ctx, args) => {

    return await ctx.db.insert("files", {

      storageId: args.storageId,

      fileName: args.fileName,

      fileType: args.fileType,

      fileSize: args.fileSize,

      uploadedAt: Date.now(),

    });

  },

});

Serving Files via URL

// convex/files.ts

export const getFileUrl = query({

  args: { storageId: v.id("_storage") },

  returns: v.union(v.string(), v.null()),

  handler: async (ctx, args) => {

    return await ctx.storage.getUrl(args.storageId);

  },

});

// Get file with URL

export const getFile = query({

  args: { fileId: v.id("files") },

  returns: v.union(

    v.object({

      _id: v.id("files"),

      fileName: v.string(),

      fileType: v.string(),

      fileSize: v.number(),

      url: v.union(v.string(), v.null()),

    }),

    v.null()

  ),

  handler: async (ctx, args) => {

    const file = await ctx.db.get(args.fileId);

    if (!file) return null;

    const url = await ctx.storage.getUrl(file.storageId);

    return {

      _id: file._id,

      fileName: file.fileName,

      fileType: file.fileType,

      fileSize: file.fileSize,

      url,

    };

  },

});

Displaying Files in React

import { useQuery } from "convex/react";

import { api } from "../convex/_generated/api";

function FileDisplay({ fileId }: { fileId: Id<"files"> }) {

  const file = useQuery(api.files.getFile, { fileId });

  if (!file) return <div>Loading...</div>;

  if (!file.url) return <div>File not found</div>;

  // Handle different file types

  if (file.fileType.startsWith("image/")) {

    return <img src={file.url} alt={file.fileName} />;

  }

  if (file.fileType === "application/pdf") {

    return (

      <iframe

        src={file.url}

        title={file.fileName}

        width="100%"

        height="600px"

      />

    );

  }

  return (

    <a href={file.url} download={file.fileName}>

      Download {file.fileName}

    </a>

  );

}

Storing Generated Files from Actions

// convex/generate.ts

"use node";

import { action } from "./_generated/server";

import { v } from "convex/values";

import { api } from "./_generated/api";

export const generatePDF = action({

  args: { content: v.string() },

  returns: v.id("_storage"),

  handler: async (ctx, args) => {

    // Generate PDF (example using a library)

    const pdfBuffer = await generatePDFFromContent(args.content);

    // Convert to Blob

    const blob = new Blob([pdfBuffer], { type: "application/pdf" });

    // Store in Convex

    const storageId = await ctx.storage.store(blob);

    return storageId;

  },

});

// Generate and save image

export const generateImage = action({

  args: { prompt: v.string() },

  returns: v.id("_storage"),

  handler: async (ctx, args) => {

    // Call external API to generate image

    const response = await fetch("https://api.example.com/generate", {

      method: "POST",

      body: JSON.stringify({ prompt: args.prompt }),

    });

    const imageBuffer = await response.arrayBuffer();

    const blob = new Blob([imageBuffer], { type: "image/png" });

    return await ctx.storage.store(blob);

  },

});

Accessing File Metadata

// convex/files.ts

import { query } from "./_generated/server";

import { v } from "convex/values";

import { Id } from "./_generated/dataModel";

type FileMetadata = {

  _id: Id<"_storage">;

  _creationTime: number;

  contentType?: string;

  sha256: string;

  size: number;

};

export const getFileMetadata = query({

  args: { storageId: v.id("_storage") },

  returns: v.union(

    v.object({

      _id: v.id("_storage"),

      _creationTime: v.number(),

      contentType: v.optional(v.string()),

      sha256: v.string(),

      size: v.number(),

    }),

    v.null()

  ),

  handler: async (ctx, args) => {

    const metadata = await ctx.db.system.get(args.storageId);

    return metadata as FileMetadata | null;

  },

});

Deleting Files

// convex/files.ts

import { mutation } from "./_generated/server";

import { v } from "convex/values";

export const deleteFile = mutation({

  args: { fileId: v.id("files") },

  returns: v.null(),

  handler: async (ctx, args) => {

    const file = await ctx.db.get(args.fileId);

    if (!file) return null;

    // Delete from storage

    await ctx.storage.delete(file.storageId);

    // Delete database record

    await ctx.db.delete(args.fileId);

    return null;

  },

});

Image Upload with Preview

import { useMutation } from "convex/react";

import { api } from "../convex/_generated/api";

import { useState, useRef } from "react";

function ImageUploader({ onUpload }: { onUpload: (id: Id<"files">) => void }) {

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

  const saveFile = useMutation(api.files.saveFile);

  const [preview, setPreview] = useState<string | null>(null);

  const [uploading, setUploading] = useState(false);

  const inputRef = useRef<HTMLInputElement>(null);

  const handleFileSelect = async (e: React.ChangeEvent<HTMLInputElement>) => {

    const file = e.target.files?.[0];

    if (!file) return;

    // Validate file type

    if (!file.type.startsWith("image/")) {

      alert("Please select an image file");

      return;

    }

    // Validate file size (max 10MB)

    if (file.size > 10 * 1024 * 1024) {

      alert("File size must be less than 10MB");

      return;

    }

    // Show preview

    const reader = new FileReader();

    reader.onload = (e) => setPreview(e.target?.result as string);

    reader.readAsDataURL(file);

    // Upload

    setUploading(true);

    try {

      const uploadUrl = await generateUploadUrl();

      const result = await fetch(uploadUrl, {

        method: "POST",

        headers: { "Content-Type": file.type },

        body: file,

      });

      const { storageId } = await result.json();

      const fileId = await saveFile({

        storageId,

        fileName: file.name,

        fileType: file.type,

        fileSize: file.size,

      });

      onUpload(fileId);

    } finally {

      setUploading(false);

    }

  };

  return (

    <div>

      <input

        ref={inputRef}

        type="file"

        accept="image/*"

        onChange={handleFileSelect}

        style={{ display: "none" }}

      />

      <button

        onClick={() => inputRef.current?.click()}

        disabled={uploading}

      >

        {uploading ? "Uploading..." : "Select Image"}

      </button>

      {preview &#x26;&#x26; (

        <img

          src={preview}

          alt="Preview"

          style={{ maxWidth: 200, marginTop: 10 }}

        />

      )}

    </div>

  );

}

Examples

Schema for File Storage

// convex/schema.ts

import { defineSchema, defineTable } from "convex/server";

import { v } from "convex/values";

export default defineSchema({

  files: defineTable({

    storageId: v.id("_storage"),

    fileName: v.string(),

    fileType: v.string(),

    fileSize: v.number(),

    uploadedBy: v.id("users"),

    uploadedAt: v.number(),

  })

    .index("by_user", ["uploadedBy"])

    .index("by_type", ["fileType"]),

  // User avatars

  users: defineTable({

    name: v.string(),

    email: v.string(),

    avatarStorageId: v.optional(v.id("_storage")),

  }),

  // Posts with images

  posts: defineTable({

    authorId: v.id("users"),

    content: v.string(),

    imageStorageIds: v.array(v.id("_storage")),

    createdAt: v.number(),

  }).index("by_author", ["authorId"]),

});

Best Practices

• Never run npx convex deploy unless explicitly instructed

• Never run any git commands unless explicitly instructed

• Validate file types and sizes on the client before uploading

• Store file metadata (name, type, size) in your own table

• Use the _storage system table only for Convex metadata

• Delete storage files when deleting database references

• Use appropriate Content-Type headers when uploading

• Consider image optimization for large images

Common Pitfalls

• Not setting Content-Type header - Files may not serve correctly

• Forgetting to delete storage - Orphaned files waste storage

• Not validating file types - Security risk for malicious uploads

• Large file uploads without progress - Poor UX for users

• Using deprecated getMetadata - Use ctx.db.system.get instead

References

• Convex Documentation: https://docs.convex.dev/

• Convex LLMs.txt: https://docs.convex.dev/llms.txt

• File Storage: https://docs.convex.dev/file-storage

• Upload Files: https://docs.convex.dev/file-storage/upload-files

• Serve Files: https://docs.convex.dev/file-storage/serve-files