---
title: "Cloudflare R2"
description: "Enable the Nuxt-side R2 upload helper and connect it to the Convex R2 component."
canonical_url: "https://nuxt-convex.onmax.me/nuxt-module/cloudflare-r2"
---
# Cloudflare R2

> Enable the Nuxt-side R2 upload helper and connect it to the Convex R2 component.

Use this guide when you want bucket-backed uploads through Cloudflare R2 instead of Convex storage objects.

## Before you begin

Make sure:

- the core module is already installed
- you have already generated `#convex/api`
- your Convex project is ready to install the `@convex-dev/r2` component

## Enable the Nuxt helper

Turn on the R2 feature in `nuxt.config.ts`.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['nuxt-convex'],
  convex: {
    r2: true,
  },
})
```

This adds the `useConvexR2Upload` auto-import. It does not create an R2-specific alias.

## Install the Convex R2 component

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

```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 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,
})
```

## Upload from Nuxt

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

const { upload, progress, isUploading, error } = useConvexR2Upload(api.r2)

async function onSelect(event: Event) {
  const file = (event.target as HTMLInputElement).files?.[0]
  if (file)
    await upload(file)
}
</script>
```

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

## Verify the result

The integration is working when:

- `useConvexR2Upload` is available without a manual import
- the file uploads successfully
- the Convex-side metadata sync completes after the upload

## Next steps

- Read [R2](https://nuxt-convex.onmax.me/integrations/r2) for the full cross-package setup
- Read [`useConvexR2Upload`](https://nuxt-convex.onmax.me/api-reference/use-convex-r2-upload) for the exact helper behavior


## Sitemap

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