---
title: "R2"
description: "Connect Cloudflare R2 to Convex and upload from Nuxt through the useConvexR2Upload helper."
canonical_url: "https://nuxt-convex.onmax.me/integrations/r2"
---
# R2

> Connect Cloudflare R2 to Convex and upload from Nuxt through the useConvexR2Upload helper.

Use this guide when you want bucket-backed uploads and metadata sync through the Convex R2 component.

The canonical validation path for this setup lives in the playground dashboard.

## Before you begin

Make sure:

- the core module is installed
- `convex.r2` is enabled in `nuxt.config.ts`
- your Convex project can install `@convex-dev/r2`

## Install the dependency

```bash [Terminal]
pnpm add @convex-dev/r2
```

## Register the Convex component

```ts [convex/convex.config.ts]
import r2 from '@convex-dev/r2/convex.config.js'
import { defineApp } from 'convex/server'

const app = defineApp()
app.use(r2)

export default app
```

## Create the Convex client API

```ts [convex/r2.ts]
import type { Auth } from 'convex/server'
import type { DataModel } from './_generated/dataModel'
import { R2 } from '@convex-dev/r2'
import { componentsGeneric } from 'convex/server'
import { ConvexError } from 'convex/values'

const components = componentsGeneric()
export const r2 = new R2(components.r2)

async function requireSignedIn(ctx: { auth: Auth }): Promise<void> {
  if (!await ctx.auth.getUserIdentity())
    throw new ConvexError('Sign in first')
}

export const {
  generateUploadUrl,
  syncMetadata,
  listMetadata,
  deleteObject,
} = r2.clientApi<DataModel>({
  // Without checks, anyone with your deployment URL can upload, list and delete
  checkUpload: requireSignedIn,
  checkReadBucket: requireSignedIn,
  checkDelete: requireSignedIn,
})
```

## Configure the environment

Set the R2 credentials in the Convex environment you are using for this deployment.

```bash [Terminal]
npx convex env set R2_BUCKET your-bucket
npx convex env set R2_ENDPOINT https://<account-id>.r2.cloudflarestorage.com
npx convex env set R2_ACCESS_KEY_ID replace-me
npx convex env set R2_SECRET_ACCESS_KEY replace-me
```

These are Convex environment variables, read by the component inside Convex, not by Nuxt.

## Upload from Nuxt

```vue [app/components/R2Upload.vue]
<script setup lang="ts">
import { api } from '#convex/api'

const { upload, progress } = useConvexR2Upload(api.r2)
</script>
```

`useConvexR2Upload` requests a signed URL from Convex, uploads the file directly to R2, and then calls `syncMetadata`.

This supported path does not add a new virtual module or a new `#convex/*` alias.

## Verify the result

The integration is working when:

- the file uploads successfully
- metadata is visible through the Convex client API
- the stored object can be listed or deleted through your R2 functions

## Next steps

- Read [Cloudflare R2](https://nuxt-convex.onmax.me/nuxt-module/cloudflare-r2) for the shorter Nuxt-module guide
- Read [`useConvexR2Upload`](https://nuxt-convex.onmax.me/api-reference/use-convex-r2-upload) for the exact helper contract


## Sitemap

See the full [sitemap](https://nuxt-convex.onmax.me/sitemap.md) for all pages.
