Convex S3

Amazon S3 storage component for Convex that generates presigned URLs for direct client uploads/downloads with cache control and stable public URLs.

Installation

npm install @hasoo/convex-s3

About Convex S3

This Convex component integrates Amazon S3 storage by generating presigned URLs that let clients upload and download files directly to/from S3 without proxying through your Convex backend. It provides cache control headers, stable public URLs for CDN integration, and handles AWS SDK v3 authentication. The component exposes actions like `generateUploadUrl` and `getSignedUrl` that your frontend can call to get time-limited S3 access URLs.

Benefits

Generate presigned S3 URLs for direct client uploads without proxying files through your server
Set cache headers like Cache-Control on uploads for optimal CDN and browser caching
Get stable public URLs alongside signed URLs for better caching strategies
Integrate S3 storage natively into Convex with minimal configuration

Use cases

how to upload files directly to S3 from Convex frontend

The Convex S3 Component generates presigned upload URLs that let clients upload files directly to S3 without routing through your server. You call the generateUploadUrl action with a key and content type, then use the returned URL for a direct PUT request to S3.

how to set cache control headers on S3 uploads in Convex

The component lets you specify cache control headers when generating upload URLs, like 'public, max-age=31536000, immutable' for static assets. You can set a default cache control policy or specify it per upload for optimal CDN caching.

how to create secure download links for S3 files in Convex

Use the getSignedUrl method to generate time-limited download URLs for private S3 objects. You can set expiration times and response headers like Content-Disposition for inline viewing or forced downloads.

how to get stable S3 URLs for caching in Convex

The component returns stable public URLs alongside presigned URLs. These stable URLs work better for browser and CDN caching since they don't rotate like signed URLs, especially when combined with versioned object keys.

Frequently asked questions

What AWS permissions does the Convex S3 Component need?

The component requires IAM permissions for s3:PutObject and s3:GetObject on your S3 bucket. You also need to configure CORS on your bucket to allow direct browser uploads with GET and PUT methods from your allowed origins.

How do I configure a CDN with the Convex S3 Component?

Set the S3_PUBLIC_BASE_URL environment variable to your CloudFront or CDN domain. The Convex S3 Component will use this as the base for stable public URLs instead of the default S3 domain, enabling better caching and performance.

Can I use the Convex S3 Component for private file downloads?

Yes, the Convex S3 Component generates presigned download URLs with configurable expiration times for secure access to private S3 objects. You can also set response headers like Content-Disposition to control how browsers handle the downloaded files.

What's the difference between signed URLs and public URLs in the Convex S3 Component?

The Convex S3 Component returns both signed URLs that expire after a set time and stable public URLs that don't change for a given object key. Stable URLs are better for caching strategies, while signed URLs provide time-limited secure access.