feat(blob): add @nuxt/image integration via image.path config

[onmax]

Fixes #521

What

Adds automatic @nuxt/image provider for NuxtHub blob storage. When @nuxt/image is installed and hub.blob.image.path is configured:

• Auto-registers nuxthub provider based on blob driver
• Cloudflare R2 → CF Image Resizing (/cdn-cgi/image/w=X,q=Y/path)
• Vercel Blob → Vercel Image Optimization (/_vercel/image?url=...&w=X&q=Y)
• FS/S3 → pass-through (no optimization)

Reproduction

Platform	Live Demo	Diff
Cloudflare R2	cloudflare-nuxthub-image-test.maximogarciamtnez.workers.dev	PR #1
Vercel Blob	nuxthub-image-test.vercel.app	PR #2
FS (no optimization)	fs-nuxthub-image-test.maximogarciamtnez.workers.dev	PR #3

Usage

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@nuxthub/core", "@nuxt/image"],
  hub: {
    blob: {
      image: {
        // Explicit path required: provider needs to know where blob.serve() route is mounted
        path: "/images"
      }
    }
  }
})

// server/routes/images/[...pathname].get.ts
import { blob } from "hub:blob"
export default defineEventHandler(async (event) => {
  const pathname = getRouterParam(event, "pathname")
  return blob.serve(event, pathname!)
})

<template>
  <NuxtImg src="/images/a-folder-in-blob-storage/photo.jpg" width="300" quality="80" />
</template>

• images: path for nuxt/nitro router
• /a-folder-in-blob-storage/photo.jpg: full path in the blob storage

Platform-Specific Notes

Cloudflare

• Custom domain with Image Resizing enabled

Vercel

• @vercel/blob installed + BLOB_READ_WRITE_TOKEN env var
• nitro.preset: vercel in nuxt.config.ts
• Important: Vercel only allows specific image widths. Add custom widths to vercel.json:

  { "images": { "sizes": [300, 640, 750, 828, 1080, 1200, 1920, 2048, 3840] } }

Technical Notes

• Requires @nuxt/image@^2.0.0 (exports runtime providers)
• Provider uses defineProvider() wrapper for proper @nuxt/image integration

Unresolved issues

Docs

Not sure if it is better to create a new Guide or leave the docs in the /features/blob

Dev mode

During testing, I noticed that dev mode doesn't work straight away:

1. In production, images are served from Blob Storage (R2/Vercel Blob).
2. In development mode, the blob storage is empty (unless the --remote flag is used).
3. The provider correctly passes through URLs in development mode
4. However, the blob route returns a 500 error because there is no image in storage.

Possible solutions

A. Require '--remote' for blob images. Document that blob images require 'nuxt dev --remote'.
B. Return a placeholder image in dev when the blob storage is empty.
C. Fallback to public folder: In dev, if the blob is empty, check the public folder as a fallback.

What is the preferred approach?

• Option A seems the simplest, but it offers slightly worse DX.
• Option B is the one I would like the most. In my experience this would be perfect.
• Option C would allow users to place development images in 'public/blob' to mirror their blob structure.

[vercel]

@onmax is attempting to deploy a commit to the NuxtLabs Team on Vercel.

A member of the Team first needs to authorize it.

[pkg-pr-new]

npm i https://pkg.pr.new/@nuxthub/core@698

commit: cca1648

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
nuxthub	Ready	Preview	Dec 10, 2025 10:36pm

[onmax]

Hey @atinux, @RihanArfan, could you please review this PR? Thank you!