ViteHub

Queue quickstart

Register Queue, define a welcome-email handler, enqueue a job from a route, and verify the queued response.

This guide creates one welcome-email queue. The route accepts an email payload, enqueues a background job, and returns a JSON response before the queue handler runs.

The provider is the only part that changes between Cloudflare and Vercel. The queue definition and producer call stay the same.

Prompt
Set up @vitehub/queue in this app.

- Install @vitehub/queue and @vercel/queue when using the Vercel provider
- Register hubQueue() for Vite or @vitehub/queue/nitro for Nitro
- Configure queue.provider as cloudflare or vercel
- Define welcome-email as a discovered queue
- Call runQueue('welcome-email', payload) from a route
- Return the queued result to the caller

Docs: /docs/vite/queue/quickstart or /docs/nitro/queue/quickstart

Install Queue

pnpm add @vitehub/queue

Install the Vercel SDK when Vercel will publish or process the queue:

Vercel
pnpm add @vercel/queue

Cloudflare uses runtime queue bindings and does not need an extra queue SDK.

Register the integration

Register the Vite plugin and choose the provider:

vite.config.ts
import { defineConfig } from 'vite'
import { hubQueue } from '@vitehub/queue/vite'

export default defineConfig({
  plugins: [hubQueue()],
  queue: {
    provider: 'cloudflare',
  },
})

Define the queue

Create a discovered Vite queue file:

src/welcome-email.queue.ts
import { defineQueue } from '@vitehub/queue'

export type WelcomeEmailPayload = {
  email: string
  template: 'default' | 'vip'
}

export default defineQueue<WelcomeEmailPayload>(async (job) => {
  console.log(`Queued ${job.payload.template} welcome email for ${job.payload.email}`)
})

Enqueue from a route

Add a Vite server entry that reads the request body and enqueues the named queue:

src/server.ts
import { H3, readBody } from 'h3'
import { runQueue } from '@vitehub/queue'
import type { WelcomeEmailPayload } from './welcome-email.queue'

const app = new H3()

app.post('/api/welcome', async (event) => {
  const payload = await readBody<WelcomeEmailPayload>(event)
  const result = await runQueue('welcome-email', payload)

  return { ok: true, payload, result }
})

export default app

Verify the response

Run or deploy the app with a configured provider, then send a request:

curl -X POST http://localhost:3000/api/welcome \
  -H 'content-type: application/json' \
  -d '{"email":"ava@example.com","template":"vip"}'

The route returns the enqueue result:

{
  "ok": true,
  "payload": {
    "email": "ava@example.com",
    "template": "vip"
  },
  "result": {
    "status": "queued",
    "messageId": "queue_7f1b6f8e-7b5c-4c5e-b3a1-8d6a4b3d4c2a"
  }
}

::

Copyright © 2026