Nuxt Blob Storage

Getting Started

Enable blob storage

Enable blob storage in your project by setting blob: true in the NuxtHub config.

nuxt.config.ts

export default defineNuxtConfig({
  hub: {
    blob: true
  }
})

Set a driver

NuxtHub automatically configures the blob storage driver based on your environment variables or hosting provider.

By default, if NuxtHub cannot detect a driver, files are stored locally in the .data/blob directory.

To set the storage directory, you can set the dir option.

nuxt.config.ts

export default defineNuxtConfig({
  hub: {
    blob: {
      driver: 'fs',
      dir: '.data/my-blob-directory' // Defaults to `.data/blob`
    }
  }
})

The local filesystem driver is not suitable for production environments.

To configure Amazon S3 as a blob storage driver.

Install the aws4fetch package

pnpm add aws4fetch

yarn add aws4fetch

npm install aws4fetch

bun add aws4fetch

deno add npm:aws4fetch

npx nypm add aws4fetch

Set the following environment variables:

.env

S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
S3_BUCKET=your-bucket-name
S3_REGION=your-region
S3_ENDPOINT=your-endpoint # (optional)

When deploying to Vercel, it automatically configures Vercel Blob Storage.

Install the @vercel/blob package

pnpm add @vercel/blob

yarn add @vercel/blob

npm install @vercel/blob

bun add @vercel/blob

deno add npm:@vercel/blob

npx nypm add @vercel/blob

Assign a Vercel Blob Store to your project from the Vercel dashboard -> Project -> Storage

Files stored in Vercel Blob are always public. Manually configure a different storage driver if storing sensitive files.

When running locally, you can set the BLOB_READ_WRITE_TOKEN environment variable to enable the Vercel Blob driver:

.env

BLOB_READ_WRITE_TOKEN=your-token

When deploying to Cloudflare, configure Cloudflare R2 by providing the bucket name. NuxtHub auto-generates the wrangler bindings at build time.

nuxt.config.ts

export default defineNuxtConfig({
  hub: {
    blob: {
      driver: 'cloudflare-r2',
      bucketName: '<bucket-name>'
    }
  }
})

Learn more about R2 bindings on Cloudflare's documentation.

To use Cloudflare R2 without hosting on Cloudflare Workers, use the Cloudflare R2 via S3 API.

Upload a file

To upload a file, you can use the blob.put() method.

import { blob } from 'hub:blob'

const file = await blob.put('avatars/user-1.png', imageData)

Learn how to upload files with validation and progress tracking.

Driver options

You can set a custom driver by providing a configuration object to blob.

nuxt.config.ts

export default defineNuxtConfig({
  hub: {
    blob: {
      driver: 'fs',
      dir: '.data/blob'
    }
  },
  // or overwrite only in production
  $production: {
    hub: {
      blob: {
        driver: 'vercel-blob'
      }
    }
  }
})

Available drivers:

export default defineNuxtConfig({
  hub: {
    blob: {
      driver: 'fs',
      dir: '.data/files' // defaults to '.data/blob'
    }
  }
})

export default defineNuxtConfig({
  hub: {
    blob: {
      driver: 's3',
      accessKeyId: 'your-access-key-id', // defaults to S3_ACCESS_KEY_ID
      secretAccessKey: 'your-secret-access-key', // defaults to S3_SECRET_ACCESS_KEY
      bucket: 'your-bucket-name', // defaults to S3_BUCKET
      region: 'your-region', // defaults to S3_REGION or 'auto'
      endpoint: 'your-endpoint' // optional, defaults to S3_ENDPOINT
    }
  }
})

export default defineNuxtConfig({
  hub: {
    blob: {
      driver: 'vercel-blob',
      token: 'your-token' // optional, defaults to BLOB_READ_WRITE_TOKEN env var
    }
  }
})

export default defineNuxtConfig({
  hub: {
    blob: {
      driver: 'cloudflare-r2',
      binding: 'BLOB' // optional, defaults to 'BLOB'
    }
  }
})

Nuxt Image Integration

@nuxt/image provides automatic image optimization. You can combine it with blob storage to serve optimized images from your storage.

Install @nuxt/image

Terminal

npx nuxt module add image

This command will install @nuxt/image and add it to your modules section of your nuxt.config.ts.

Configure the image provider

Configure @nuxt/image to use the appropriate provider for your hosting platform:

nuxt.config.ts

export default defineNuxtConfig({
  image: {
    provider: 'cloudflare',
    cloudflare: { baseURL: '/images' }
  }
})

See Cloudflare provider docs for requirements and options.

When deploying to Vercel, it automatically configures the Vercel Image provider.

nuxt.config.ts

export default defineNuxtConfig({
  image: {
    provider: 'vercel'
  }
})

See Vercel provider docs for requirements and options.

Use NuxtImg or NuxtPicture

Use the components to display optimized images from blob storage:

pages/gallery.vue

<template>
  <NuxtImg src="/images/photo.jpg" width="300" quality="80" />
</template>

The src path combines your route prefix (/images) with the blob pathname (photo.jpg).