Vercel Queue

Install the provider SDK

pnpm add @vercel/queue

Configure Queue

Register the Nitro module and set queue.provider to vercel:

import { defineNitroConfig } from 'nitro/config'

export default defineNitroConfig({
  modules: ['@vitehub/queue/nitro'],
  queue: {
    provider: 'vercel',
    region: 'fra1',
  },
})

Resolve the region

Set queue.region when you want an explicit send region.

Queue resolves the Vercel region in this order:

1. queue.region
2. QUEUE_REGION
3. VERCEL_REGION
4. Vercel request headers

If Queue cannot resolve a region for the current @vercel/queue client, the provider throws VERCEL_QUEUE_REGION_REQUIRED.

Understand topic names

Queue derives Vercel topics from discovered queue names.

For welcome-email:

Use getVercelQueueTopicName() when another integration needs the exact topic:

import { getVercelQueueTopicName } from '@vitehub/queue'

console.log(getVercelQueueTopicName('welcome-email'))

Use hosted callbacks

ViteHub generates hosted callback functions for discovered queues during provider output generation.

The generated callback:

1. Loads the queue definition from the registry.
2. Resolves the active Vercel queue client.
3. Calls handleHostedVercelQueueCallback().
4. Delivers the payload to your defineQueue() handler.

You can also wire the callback manually when needed:

import { handleHostedVercelQueueCallback } from '@vitehub/queue'
import definition from '../../queues/welcome-email'

export default defineEventHandler((event) => {
  return handleHostedVercelQueueCallback(event, 'welcome-email', definition)
})

Tune callback behavior

Use callbackOptions on the queue definition:

import { defineQueue } from '@vitehub/queue'

export default defineQueue<{ email: string }>(async (job) => {
  console.log(job.payload.email)
}, {
  callbackOptions: {
    visibilityTimeoutSeconds: 60,
    retry(error, metadata) {
      return { afterSeconds: 30 }
    },
  },
})

Return { acknowledge: true } from retry() when a failed message should be acknowledged instead of retried.

Generated output

For Vercel Nitro presets, the module writes queue callback functions under .output/functions/api/vitehub/queues/vercel.

Each generated callback function includes a Vercel queue trigger for the derived topic.

Verify the provider

Call a route that enqueues a known queue:

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

Successful publishing returns a queued result:

{
  "ok": true,
  "result": {
    "status": "queued",
    "messageId": "message-1"
  }
}