Add File Uploads to Your App

The recommended pattern is direct browser-to-storage uploads using presigned URLs — this avoids routing large files through your server and reduces bandwidth costs. Your server generates a short-lived signed URL, the browser uploads directly to S3 or Supabase Storage, and then notifies your server when complete. Server-side uploads are simpler but bottleneck your API and can hit serverless function payload limits. For files larger than a few megabytes, always use direct uploads.

Create a storage bucket in the Supabase dashboard and configure public or private access based on your needs. Install `@supabase/supabase-js` and call `supabase.storage.from('bucket').upload(path, file)` from the browser to upload directly. For private files, generate a signed URL with `createSignedUrl` when you need to display them. Set bucket policies to restrict file types and sizes to prevent abuse.

Install `@aws-sdk/s3-request-presigner` and create an API route that calls `getSignedUrl` with a `PutObjectCommand`. Set an expiry of 60 seconds and restrict the allowed content type to the expected file format. Return the presigned URL and the final file URL to the client. In the browser, PUT the file directly to the presigned URL using `fetch` with the file as the body and the matching `Content-Type` header.

Validate file type and size on the client before requesting a presigned URL to give instant feedback. Check `file.type` against an allowlist of MIME types and enforce a maximum size in megabytes. Re-validate on the server when generating the presigned URL by inspecting the requested content type and rejecting anything outside your allowlist. Never trust client-side validation alone — always enforce limits server-side.

Use `XMLHttpRequest` instead of `fetch` for presigned URL uploads if you need progress events — `xhr.upload.onprogress` fires with `loaded` and `total` byte counts. Compute the percentage and update a progress bar in state. Alternatively, use a library like `uppy` or `react-dropzone` with a tus or S3 multipart plugin for resumable uploads with built-in progress UI. Show a thumbnail preview immediately after the user selects a file using `URL.createObjectURL`.

For images, use a CDN or image transformation service like Cloudflare Images or Imgix to serve optimized WebP versions at the right dimensions. Store only the base file path in your database and construct CDN URLs at render time. For private documents, always generate short-lived signed URLs rather than exposing the raw storage URL. Set appropriate Cache-Control headers on public assets to maximize CDN hit rates.