---
title: "File Storage"
description: "Configure the Vue storage plugin, upload files, and read file URLs reactively."
canonical_url: "https://nuxt-convex.onmax.me/vue-guide/file-storage"
---
# File Storage

> Configure the Vue storage plugin, upload files, and read file URLs reactively.

Use this guide when you want storage helpers in a standalone Vue app.

## Before you begin

Make sure:

- the base `convexVue` plugin is already installed
- you already have generated Convex types
- your Convex backend exposes storage functions you can pass to the storage plugin
- your client is signed in (see [Authentication](https://nuxt-convex.onmax.me/vue-guide/authentication)); the functions below reject anonymous calls, so uploads fail with `ConvexError: Unauthenticated` until it is

## Create the backend functions

```ts [convex/storage.ts]
import type { Auth } from 'convex/server'
import { ConvexError, v } from 'convex/values'
import { mutation, query } from './_generated/server'

async function requireIdentity(ctx: { auth: Auth }) {
  const identity = await ctx.auth.getUserIdentity()
  if (!identity)
    throw new ConvexError('Unauthenticated')
  return identity
}

export const generateUploadUrl = mutation({
  args: {},
  handler: async (ctx) => {
    await requireIdentity(ctx)
    return await ctx.storage.generateUploadUrl()
  },
})

export const getUrl = query({
  args: { storageId: v.id('_storage') },
  handler: async (ctx, { storageId }) => {
    await requireIdentity(ctx)
    return await ctx.storage.getUrl(storageId)
  },
})

export const remove = mutation({
  args: { storageId: v.id('_storage') },
  handler: async (ctx, { storageId }) => {
    await requireIdentity(ctx)
    await ctx.storage.delete(storageId)
  },
})
```

These are public functions: without the identity check, anyone with your deployment URL could upload and delete files. Before production, also record who uploaded each file and check it in `getUrl` and `remove`.

## Register the storage plugin

```ts [src/main.ts]
import { convexVue } from 'vue-convex'
import { convexVueStorage } from 'vue-convex/storage'
import { createApp } from 'vue'
import { api } from '../convex/_generated/api'
import App from './App.vue'

const app = createApp(App)

app.use(convexVue, {
  url: import.meta.env.VITE_CONVEX_URL,
})

app.use(convexVueStorage, {
  generateUploadUrl: api.storage.generateUploadUrl,
  getUrl: api.storage.getUrl,
  remove: api.storage.remove,
})

app.mount('#app')
```

## Upload a file

```vue [src/components/FileUpload.vue]
<script setup lang="ts">
import { useConvexUpload } from 'vue-convex/storage'

const { upload, isUploading, progress, error } = useConvexUpload({
  onSuccess(storageId, file) {
    console.log(`Uploaded ${file.name} as ${storageId}`)
  },
})

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

## Read the file URL

```vue [src/components/AvatarUpload.vue]
<script setup lang="ts">
import { ref } from 'vue'
import { useConvexStorage, useConvexUpload } from 'vue-convex/storage'

const storage = useConvexStorage()
const storageId = ref<string | null>(null)
const url = storage.getUrl(storageId)

const { upload } = useConvexUpload({
  onSuccess(id) {
    storageId.value = id
  },
})
</script>
```

`useConvexStorage().getUrl(storageId)` returns a ref backed by a live query. It follows a reactive `storageId`, and is `null` while loading or when the id is empty. Call it in `setup()`: each call subscribes in the current scope.

## Verify the result

The setup is working when:

- the storage plugin installs without errors
- `upload(file)` returns a `storageId`
- `getUrl(storageId)` resolves to a public URL

Uploads are client-only. Calling `upload()` during SSR returns `null` and sets an error.

## Next steps

- Read [Controller](https://nuxt-convex.onmax.me/vue-guide/controller) if the storage setup depends on delayed connection
- Read [`useConvexStorage`](https://nuxt-convex.onmax.me/api-reference/use-convex-storage) and [`useConvexUpload`](https://nuxt-convex.onmax.me/api-reference/use-convex-upload) for the exact API surface


## Sitemap

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