Blob

@vitehub/blob gives Vite and Nitro apps one server-side Blob API for local files, Cloudflare R2, and Vercel Blob.

Use Blob when routes need to accept user files, write generated assets, list stored objects, or stream a stored file back through the application.

import { createError, defineEventHandler, readFormData } from 'h3'
import { blob, ensureBlob } from '@vitehub/blob'

export default defineEventHandler(async (event) => {
  const form = await readFormData(event)
  const file = form.get('file')

  if (!(file instanceof Blob)) {
    throw createError({ statusCode: 400, statusMessage: 'Expected a file upload.' })
  }

  ensureBlob(file, { maxSize: '1MB', types: ['image'] })

  return await blob.put('avatar.png', file, {
    addRandomSuffix: true,
    prefix: 'avatars',
  })
})

{
  "pathname": "avatars/avatar-a1b2c3d4.png",
  "contentType": "image/png",
  "size": 8421,
  "httpEtag": "\"6f1d...\"",
  "uploadedAt": "2026-04-26T12:00:00.000Z",
  "httpMetadata": {
    "contentType": "image/png"
  },
  "customMetadata": {}
}

What Blob Solves

Object storage APIs differ by platform. Blob keeps route code focused on pathnames, bodies, metadata, and streams while the active driver handles provider details.

One Portable Flow

The same shape works across supported runtimes:

1. Install @vitehub/blob.
2. Register hubBlob() for Vite or @vitehub/blob/nitro for Nitro.
3. Choose a storage driver or let hosting inference pick one.
4. Use blob.put(), blob.list(), blob.get(), blob.head(), blob.del(), and blob.serve() from server routes.
5. Move provider-specific tokens, bindings, and bucket names into config or environment.

Storage Resolution

ViteHub resolves Blob storage in this order:

1. Explicit blob.driver config wins.
2. Cloudflare hosting resolves cloudflare-r2.
3. BLOB_READ_WRITE_TOKEN resolves vercel-blob.
4. Vercel hosting resolves vercel-blob.
5. Everything else falls back to fs at .data/blob.

Supported Storage Paths

Start Here

Start with Quickstart for a local fs setup. Use the primitive comparison when you are choosing between Blob, KV, Queue, Sandbox, and inline response data.

Next Steps