---
name: bijection-r2
description: "Evaluate and integrate the Cloudflare R2 component with Bijection."
---

# Cloudflare R2

Cloudflare R2 file storage

- Package: @bijectionhq/r2
- Category: Storage
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/r2/tree/c4240ac2ab0c25534df13b72ec776f7d0aad98db
- Upstream: https://github.com/convex/r2/tree/e70ed03ce1d7103d42ae1e3ff5129f6cdbb193e3
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/r2

## Get the source

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

```sh
git clone https://github.com/bijectionhq/r2.git
cd r2
git checkout c4240ac2ab0c25534df13b72ec776f7d0aad98db
```

## 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 @convex-dev/r2. 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 Cloudflare R2. Follow the installation and configuration steps exactly.

# Cloudflare R2

## Instructions

The Cloudflare R2 component provides file storage and serving capabilities using Cloudflare's R2 object storage service. It handles signed URL generation for uploads, syncs file metadata to your Convex database, and provides React/Svelte hooks for seamless client-side file operations. The component supports multiple buckets, custom object keys, and server-side file storage from actions.

### Installation

```bash
npm install @convex-dev/r2
```

Current npm version: `@convex-dev/r2@0.10.4`

## Use cases

- **User-generated content uploads** where users need to upload profile pictures, documents, or media files directly from your React or Svelte frontend
- **Server-side file processing** where actions download external images, generate documents, or process data that needs to be stored in R2 and associated with database records
- **Multi-tenant applications** where different customers or projects require separate R2 buckets with isolated file storage
- **Content management systems** that need to store and serve large files while keeping metadata searchable in Convex tables
- **File sharing applications** where you need to generate time-limited URLs for secure file access with custom expiration times

## How it works

The component creates an R2 instance that connects to your Cloudflare bucket using API credentials stored as environment variables. For uploads, it generates signed URLs through the `generateUploadUrl` function and provides `useUploadFile` hooks for React and Svelte that handle the complete upload flow including metadata syncing.

File metadata gets stored in Convex tables alongside the R2 storage, enabling you to query and associate files with other data. The `clientApi` method lets you define upload validation and post-upload callbacks with proper TypeScript typing when you pass your DataModel as a generic parameter.

For server-side operations, the `r2.store` method accepts Blobs, Buffers, or Uint8Arrays from actions and handles both R2 upload and metadata syncing. File serving uses `r2.getUrl` to generate time-limited access URLs with configurable expiration times, and `r2.deleteObject` removes files from both R2 and your database.

## 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 Cloudflare R2 is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Fr2)
- [GitHub repository](https://github.com/get-convex/r2)
- [Live demo](https://github.com/get-convex/r2/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/cloudflare-r2)
- [Convex documentation](https://docs.convex.dev)