convex-file-storage_skill

Overview

This skill provides end-to-end file handling patterns for Convex apps, including upload URL generation, client upload flows, serving files via generated URLs, storing generated files from server actions, deletion, and metadata access. It delivers ready-to-use mutations, queries, and React examples to integrate file storage safely and predictably into production apps.

How this skill works

Server-side helpers generate signed upload URLs and store file blobs in Convex storage. Client code uploads files to the generated URL, then saves a reference (storageId, name, type, size) into a user-managed table. Queries fetch storage URLs via ctx.storage.getUrl and system metadata via ctx.db.system.get; actions can generate files, store them with ctx.storage.store, and return storage IDs.

When to use it

• Uploading user images, documents, or videos from a browser or mobile app
• Serving files publicly or embedding images/PDFs via generated URLs
• Saving server-generated artifacts (PDFs, generated images) from actions
• Keeping searchable file metadata in your own tables while using Convex storage for blobs
• Implementing secure, signed upload flows to avoid routing large files through your server

Best practices

• Validate file type and size on the client before requesting an upload URL
• Always set the correct Content-Type header when uploading to the signed URL
• Store human-friendly metadata (fileName, fileType, fileSize, uploadedAt, uploadedBy) in your own table
• Delete both the storage blob and the DB reference when removing a file to avoid orphaned storage
• Use ctx.db.system.get to read storage metadata (size, sha256, creation time), not deprecated helpers

Example use cases

• Image uploader with client-side preview and Convex-backed storageId referenced in a files table
• Server action that generates a PDF or image, stores it in Convex storage, and returns a storageId to save
• File viewer that returns a file record with a getUrl result and renders images, PDFs or download links
• File lifecycle management: upload -> save reference -> serve -> delete (storage + DB) as part of user actions