Blob

Use Blob for uploads, generated media, PDFs, exports, and other objects that don't need a file tree.

Use Workspace when files need paths, snapshots, diffs, Source sync, or agent access. A Blob Store only keeps objects and their metadata.

Quick start

pnpm add @vite-hub/blob

import { hubBlob } from '@vite-hub/blob/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [hubBlob()],
})

import { blob } from '@vite-hub/blob'

export default defineEventHandler(async () => {
  const [error, object] = await blob.put('hello.txt', 'Hello from ViteHub')
  if (error) throw error
  return object
})

Public imports

All Blob driver, object, list, put, store, and module types are exported from @vite-hub/blob.

Blob writes preserve the metadata you provide. detectContentType() checks common leading signatures, but it doesn't validate the complete file or prove that the file is safe.

Store configuration

Configure one default Blob Store directly, or configure named stores with blob.stores.

export default defineConfig({
  plugins: [hubBlob()],
  blob: {
    stores: {
      default: { driver: 'fs' },
      reports: { driver: 'vercel-blob', access: 'private' },
    },
  },
})

Provider options

Every Blob Store config is a discriminated union selected by driver. Keep credentials in Server Env or provider-managed secrets; fields in these tables describe the exact public config shape, not a recommendation to commit secrets to Vite config.

Local filesystem

Filesystem storage is for local or single-process use. It does not become durable shared storage on a serverless host.

Cloudflare R2

The runtime binding takes precedence. HTTP credentials are used when no active binding exists.

Vercel Blob

Netlify Blobs

S3 and S3-compatible providers

The s3, akamai, digitalocean-spaces, hetzner, storj, and minio drivers share object-storage routing options. Their required fields differ.

MinIO resolves credentials from MINIO_ACCESS_KEY_ID, MINIO_ACCESS_KEY, MINIO_ROOT_USER, or AWS_ACCESS_KEY_ID, with matching secret-key env aliases. Other S3-compatible adapters also support their provider or SDK credential sources.

Google Cloud Storage

Azure Blob Storage

Supabase Storage

UploadThing

Google Drive

OneDrive

Dropbox

Box

Use it at runtime

Use the blob Runtime Helper from server code.

import { blob } from '@vite-hub/blob'

export default defineEventHandler(async (event) => {
  const body = await readBody<{ path: string, text: string }>(event)

  const [error] = await blob.put(body.path, body.text, {
    contentType: 'text/plain',
    customMetadata: { source: 'api' },
  })
  if (error) throw error

  return { ok: true }
})

import { blob } from '@vite-hub/blob'

export default defineEventHandler(async (event) => {
  const path = getRouterParam(event, 'path')!
  const [error, object] = await blob.get(path)
  if (error) throw error

  if (!object) {
    throw createError({ statusCode: 404 })
  }

  return object
})

Use named Blob Stores when configuration defines multiple stores.

import { blob } from '@vite-hub/blob'

export const reports = blob.store('reports')

Serve blob-backed assets

Blob serving is opt-in. Set serve in the Blob config, or pass hubBlob({ serve: true }), to generate a Nitro route that serves Blob-backed assets through blob.serve().

export default defineConfig({
  plugins: [hubBlob()],
  blob: {
    driver: 'fs',
    serve: true,
  },
})

serve: true uses /api/_vitehub/blob as the route base. ViteHub chooses a namespaced API route by default so generated handlers avoid app routes, static assets, and framework asset directories. The default also mirrors server API route conventions.

Use an explicit serve.route for product-facing asset URLs.

export default defineConfig({
  plugins: [hubBlob()],
  blob: {
    driver: 's3',
    bucket: 'app-assets',
    serve: {
      route: '/assets',
      headers: {
        'Cache-Control': 'public, max-age=300',
        'X-Content-Type-Options': 'nosniff',
      },
    },
  },
})

Use serve.headers for static cache and security policy. Blob metadata remains authoritative for content headers such as Content-Type, Content-Length, and ETag.

The generated Nitro route maps ${route}/** to the selected Blob Store and delegates streaming to blob.store(storeName).serve(event, pathname). The default route is a safe framework default. It is not a recommendation that every app expose public assets under /api.

Objects from the served store include a URL. With serve.publicBaseUrl, the URL is absolute. Without it, the URL is route-relative so request-aware consumers can resolve it against their own origin.

Runtime helper

blob implements BlobStorage.

Every async method returns [error, value]. Expected provider and storage failures are ViteHubError values with BLOB_* codes, so application code can apply HTTP, retry, logging, or best-effort policy without try/catch. Invalid arguments, unknown stores, and unsupported signing capabilities still throw because they indicate API or configuration misuse. Generated serving routes unwrap blob.serve() and pass its error to H3.

Write options

Signed requests

Use blob.sign() when a client or provider needs short-lived direct access to one private object. The result contains the URL, HTTP method, and every header that must be sent with the request.

import { blob } from '@vite-hub/blob'

const [sourceError, source] = await blob.sign('users/user/jobs/job/source.mp3', {
  method: 'GET',
  expiresIn: 6 * 60 * 60,
})
if (sourceError) throw sourceError

const [uploadError, upload] = await blob.sign('users/user/jobs/job/source.mp3', {
  method: 'PUT',
  expiresIn: 15 * 60,
  contentType: 'audio/mpeg',
  createOnly: true,
})
if (uploadError) throw uploadError

Send upload.headers unchanged with the PUT body. contentType binds the upload MIME type into the signed request. createOnly binds a provider condition that rejects the upload when the object already exists; drivers that cannot enforce it throw instead of silently allowing an overwrite.

Cloudflare R2 signs through its S3-compatible HTTP credentials, including when normal reads and writes use a Workers binding. A binding alone cannot mint a presigned URL, so configure accountId, accessKeyId, secretAccessKey, and bucketName through runtime environment values. R2 presigned URLs accept expiries from 1 second through 7 days, and the S3 compatibility contract supports If-None-Match on PutObject.

ensureBlob(blob, options)

Use ensureBlob() at upload boundaries.

Provider output

The Blob package selects the default or named store and loads its driver. Put provider bucket names, tokens, and bindings in integration configuration or deployment setup.

Application code keeps importing blob from @vite-hub/blob when you switch providers.

Connect Blob to Agents

Direct Blob access is for server code. To let a model inspect or edit scoped object storage, attach the Blob Capability.

Give a Blob Capability the narrowest useful key prefix and configure write access deliberately. Use Workspace when the model needs a file tree, diffs, snapshots, or Source-backed context.

Production checks

Store content types and metadata at write time. Avoid guessing object type later from path names.

Blob can store Workspace data, but it doesn't provide a file tree to an Agent. Workspace handles file operations, rules, snapshots, and diffs.

Blob stores binary objects and small object metadata. Keep catalogs, indexes, permissions, search records, domain records, and richer metadata queries in KV, Database, or another NoSQL/catalog store next to Blob.

Cloudflare R2 bucket

Cloudflare R2 Blob Stores use the configured runtime binding when it exists. binding defaults to BLOB, and bucketName lets ViteHub emit the matching Cloudflare R2 bucket binding in Provider Output.

export default defineConfig({
  blob: {
    driver: 'cloudflare-r2',
    binding: 'BLOB',
    bucketName: 'assets',
  },
})

When no runtime binding exists, ViteHub falls back to R2 HTTP access through files-sdk/r2. Set accessKeyId and secretAccessKey with runtime env, not vite.config.ts; non-secret values such as bucketName can stay in config.

R2_ACCOUNT_ID=account-id
R2_ACCESS_KEY_ID=access-key-id
R2_SECRET_ACCESS_KEY=secret-access-key
R2_BUCKET_NAME=assets

Install the optional R2 HTTP dependencies only when you rely on fallback access.

pnpm add files-sdk @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

S3-compatible object storage

Use driver: 's3' for production S3-compatible object storage that is not one of ViteHub's provider-specific drivers.

pnpm add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

export default defineConfig({
  blob: {
    driver: 's3',
    bucket: 'app-assets',
    endpoint: process.env.S3_ENDPOINT,
    region: process.env.S3_REGION,
    publicBaseUrl: 'https://assets.example.com',
  },
})

Store S3 credentials in Server Env or the provider credential chain used by the S3 SDK. Put non-secret routing values such as bucket, endpoint, region, and publicBaseUrl in config.

Use Cloudflare R2 when the app runs with an R2 binding or R2 HTTP credentials. Use MinIO when local development or Docker Compose needs to exercise S3-compatible behavior.

MinIO object storage

Use MinIO when you want Docker Compose or local staging to exercise object-storage semantics instead of a mounted filesystem.

pnpm add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

export default defineConfig({
  blob: {
    driver: 'minio',
  },
})

MINIO_ENDPOINT=http://minio:9000
MINIO_ROOT_USER=minio
MINIO_ROOT_PASSWORD=password
BLOB_BUCKET_NAME=vitehub-blob

ViteHub reads MinIO credentials from runtime env and masks them in generated provider output. It accepts the Files SDK names MINIO_ACCESS_KEY_ID and MINIO_SECRET_ACCESS_KEY, plus Docker Compose aliases such as MINIO_ROOT_USER and MINIO_ROOT_PASSWORD. driver: 'minio' defaults to path-style S3 requests, us-east-1, http://localhost:9000, and the vitehub-blob bucket. For production Docker deployments, use managed s3 or a production S3-compatible store instead of a single-host Compose MinIO service.

Next steps

• Use Workspace for file-tree state.
• Use Source for read-only retrieval.
• Expose scoped model access through Official capabilities.