convex-file-storage
installsforks
How to install convex-file-storage?
waynesutton/convexskills/convex-file-storage
$npx -y skills add waynesutton/convexskills --skill convex-file-storageComplete file handling including upload flows, serving files via URL, storing generated files from actions, deletion, and accessing file metadata from system tables
SKILL.md
| 1 | # Convex File Storage |
| 2 | |
| 3 | Handle file uploads, storage, serving, and management in Convex applications with proper patterns for images, documents, and generated files. |
| 4 | |
| 5 | ## Documentation Sources |
| 6 | |
| 7 | Before implementing, do not assume; fetch the latest documentation: |
| 8 | |
| 9 | - Primary: https://docs.convex.dev/file-storage |
| 10 | - Upload Files: https://docs.convex.dev/file-storage/upload-files |
| 11 | - Serve Files: https://docs.convex.dev/file-storage/serve-files |
| 12 | - For broader context: https://docs.convex.dev/llms.txt |
| 13 | |
| 14 | ## Instructions |
| 15 | |
| 16 | ### File Storage Overview |
| 17 | |
| 18 | Convex provides built-in file storage with: |
| 19 | - Automatic URL generation for serving files |
| 20 | - Support for any file type (images, PDFs, videos, etc.) |
| 21 | - File metadata via the `_storage` system table |
| 22 | - Integration with mutations and actions |
| 23 | |
| 24 | ### Generating Upload URLs |
| 25 | |
| 26 | ```typescript |
| 27 | // convex/files.ts |
| 28 | import { mutation } from "./_generated/server"; |
| 29 | import { v } from "convex/values"; |
| 30 | |
| 31 | export const generateUploadUrl = mutation({ |
| 32 | args: {}, |
| 33 | returns: v.string(), |
| 34 | handler: async (ctx) => { |
| 35 | return await ctx.storage.generateUploadUrl(); |
| 36 | }, |
| 37 | }); |
| 38 | ``` |
| 39 | |
| 40 | ### Client-Side Upload |
| 41 | |
| 42 | ```typescript |
| 43 | // React component |
| 44 | import { useMutation } from "convex/react"; |
| 45 | import { api } from "../convex/_generated/api"; |
| 46 | import { useState } from "react"; |
| 47 | |
| 48 | function FileUploader() { |
| 49 | const generateUploadUrl = useMutation(api.files.generateUploadUrl); |
| 50 | const saveFile = useMutation(api.files.saveFile); |
| 51 | const [uploading, setUploading] = useState(false); |
| 52 | |
| 53 | const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => { |
| 54 | const file = e.target.files?.[0]; |
| 55 | if (!file) return; |
| 56 | |
| 57 | setUploading(true); |
| 58 | try { |
| 59 | // Step 1: Get upload URL |
| 60 | const uploadUrl = await generateUploadUrl(); |
| 61 | |
| 62 | // Step 2: Upload file to storage |
| 63 | const result = await fetch(uploadUrl, { |
| 64 | method: "POST", |
| 65 | headers: { "Content-Type": file.type }, |
| 66 | body: file, |
| 67 | }); |
| 68 | |
| 69 | const { storageId } = await result.json(); |
| 70 | |
| 71 | // Step 3: Save file reference to database |
| 72 | await saveFile({ |
| 73 | storageId, |
| 74 | fileName: file.name, |
| 75 | fileType: file.type, |
| 76 | fileSize: file.size, |
| 77 | }); |
| 78 | } finally { |
| 79 | setUploading(false); |
| 80 | } |
| 81 | }; |
| 82 | |
| 83 | return ( |
| 84 | <div> |
| 85 | <input |
| 86 | type="file" |
| 87 | onChange={handleUpload} |
| 88 | disabled={uploading} |
| 89 | /> |
| 90 | {uploading && <p>Uploading...</p>} |
| 91 | </div> |
| 92 | ); |
| 93 | } |
| 94 | ``` |
| 95 | |
| 96 | ### Saving File References |
| 97 | |
| 98 | ```typescript |
| 99 | // convex/files.ts |
| 100 | import { mutation, query } from "./_generated/server"; |
| 101 | import { v } from "convex/values"; |
| 102 | |
| 103 | export const saveFile = mutation({ |
| 104 | args: { |
| 105 | storageId: v.id("_storage"), |
| 106 | fileName: v.string(), |
| 107 | fileType: v.string(), |
| 108 | fileSize: v.number(), |
| 109 | }, |
| 110 | returns: v.id("files"), |
| 111 | handler: async (ctx, args) => { |
| 112 | return await ctx.db.insert("files", { |
| 113 | storageId: args.storageId, |
| 114 | fileName: args.fileName, |
| 115 | fileType: args.fileType, |
| 116 | fileSize: args.fileSize, |
| 117 | uploadedAt: Date.now(), |
| 118 | }); |
| 119 | }, |
| 120 | }); |
| 121 | ``` |
| 122 | |
| 123 | ### Serving Files via URL |
| 124 | |
| 125 | ```typescript |
| 126 | // convex/files.ts |
| 127 | export const getFileUrl = query({ |
| 128 | args: { storageId: v.id("_storage") }, |
| 129 | returns: v.union(v.string(), v.null()), |
| 130 | handler: async (ctx, args) => { |
| 131 | return await ctx.storage.getUrl(args.storageId); |
| 132 | }, |
| 133 | }); |
| 134 | |
| 135 | // Get file with URL |
| 136 | export const getFile = query({ |
| 137 | args: { fileId: v.id("files") }, |
| 138 | returns: v.union( |
| 139 | v.object({ |
| 140 | _id: v.id("files"), |
| 141 | fileName: v.string(), |
| 142 | fileType: v.string(), |
| 143 | fileSize: v.number(), |
| 144 | url: v.union(v.string(), v.null()), |
| 145 | }), |
| 146 | v.null() |
| 147 | ), |
| 148 | handler: async (ctx, args) => { |
| 149 | const file = await ctx.db.get(args.fileId); |
| 150 | if (!file) return null; |
| 151 | |
| 152 | const url = await ctx.storage.getUrl(file.storageId); |
| 153 | |
| 154 | return { |
| 155 | _id: file._id, |
| 156 | fileName: file.fileName, |
| 157 | fileType: file.fileType, |
| 158 | fileSize: file.fileSize, |
| 159 | url, |
| 160 | }; |
| 161 | }, |
| 162 | }); |
| 163 | ``` |
| 164 | |
| 165 | ### Displaying Files in React |
| 166 | |
| 167 | ```typescript |
| 168 | import { useQuery } from "convex/react"; |
| 169 | import { api } from "../convex/_generated/api"; |
| 170 | |
| 171 | function FileDisplay({ fileId }: { fileId: Id<"files"> }) { |
| 172 | const file = useQuery(api.files.getFile, { fileId }); |
| 173 | |
| 174 | if (!file) return <div>Loading...</div>; |
| 175 | if (!file.url) return <div>File not found</div>; |
| 176 | |
| 177 | // Handle different file types |
| 178 | if (file.fileType.startsWith("image/")) { |
| 179 | return <img src={file.url} alt={file.fileName} />; |
| 180 | } |
| 181 | |
| 182 | if (file.fileType === "application/pdf") { |
| 183 | return ( |
| 184 | <iframe |
| 185 | src={file.url} |
| 186 | title={file.fileName} |
| 187 | width="100%" |
| 188 | height="600px" |
| 189 | /> |
| 190 | ); |
| 191 | } |
| 192 | |
| 193 | return ( |
| 194 | <a href={file.url} download={file.fileName}> |
| 195 | Download {file.fileName} |
People who liked this also viewed
6 picksType
- azure-storageAzure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier,SkillsJul 2026
- supabase-postgres-best-practicesPostgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.SkillsJul 2026
- supabaseUse when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, SkillsJul 2026
- convex-quickstartCreates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.SkillsJul 2026
- convex-performance-auditAudits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.SkillsJul 2026
- convex-setup-authSets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.SkillsJul 2026
