---
name: bijection-s3
description: "Evaluate and integrate the Amazon S3 component with Bijection."
---

# Amazon S3

S3 uploads and downloads

- Package: @bijectionhq/s3
- Category: Storage
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/s3/tree/dbf784d116622da5871f9843073bd75bfc44696a
- Upstream: https://github.com/H4S0/convex-S3-component/tree/6e069e1b5edaa0e526392b475350ff14df758728
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/s3

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/s3.git
cd s3
git checkout dbf784d116622da5871f9843073bd75bfc44696a
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @hasoo/convex-s3. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Convex S3. Follow the installation and configuration steps exactly.

# Convex S3

## Instructions

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.

### Installation

```bash
npm install @hasoo/convex-s3
```

Current npm version: `@hasoo/convex-s3@0.3.0`

## Use cases

- **Direct file uploads** - Let users upload images, documents, or media files straight to S3 from the browser without hitting your server
- **Secure file downloads** - Generate time-limited download URLs for private content like user documents or premium assets
- **CDN integration** - Use stable public URLs with CloudFront or other CDNs for cached static assets with proper cache headers
- **Large file handling** - Bypass Convex's file size limits by storing large uploads directly in S3 while keeping metadata in Convex
- **Asset versioning** - Implement cache-busting strategies with versioned object keys and immutable cache headers

## How it works

The component wraps the AWS SDK v3 S3 client and exposes Convex actions for generating presigned URLs. You configure it by adding AWS credentials and bucket settings to your Convex environment variables, then register it in `convex.config.ts` using `app.use(s3)`.

The main API includes `generateUploadUrl()` which returns both a presigned upload URL and a stable public URL, and `getSignedUrl()` for creating time-limited download links. You can set cache control headers during upload generation and configure response headers like `Content-Disposition` for downloads.

For production use, the component supports a `publicBaseUrl` option to point stable URLs at your CloudFront distribution instead of direct S3 URLs. This enables proper CDN caching while keeping the presigned URLs for actual upload/download operations. Your S3 bucket needs CORS configuration to allow direct browser uploads and appropriate IAM permissions for `s3:PutObject` and `s3:GetObject` operations.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Convex S3 is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40hasoo%2Fconvex-s3)
- [GitHub repository](https://github.com/H4S0/convex-S3-component)
- [Live demo](https://github.com/H4S0/convex-S3-component)
- [Convex Components Directory](https://www.convex.dev/components/hasoo/convex-s3)
- [Convex documentation](https://docs.convex.dev)