QStash Queue
Configure Upstash QStash for queues and signed callback delivery.
QStash fits apps that prefer an HTTP-first queue with signed callback delivery. ViteHub keeps queue definitions in server/queues/**, while QStash handles publishing, callback delivery, and message verification.
Install the SDK
Terminal
pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/queue@main @upstash/qstash
Configure QStash
nuxt.config.ts
export default defineNuxtConfig({
modules: ['@vitehub/queue/nuxt'],
queue: {
provider: 'qstash',
token: process.env.QSTASH_TOKEN!,
destination: 'https://example.com/api/queue/welcome',
},
})
token is required. destination gives runQueue() a default callback URL so you do not need to repeat it for every send.
Define a queue
server/queues/welcome-email.ts
import { defineQueue } from '@vitehub/queue'
export default defineQueue(async (job) => {
return {
email: job.payload?.email,
}
}, {
destination: 'https://example.com/api/queue/welcome',
})
Verify callbacks
Use verifyQStashSignature() when your callback route should reject unsigned requests.
server/api/queue/welcome.post.ts
import { verifyQStashSignature } from '@vitehub/queue'
export default defineEventHandler(async (event) => {
const ok = await verifyQStashSignature(event.node.req as unknown as Request, {
currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY!,
nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY,
})
return { ok }
})
What changes on QStash
| Concern | Behavior |
|---|---|
| Destination | Set a global queue.destination or override it per queue with destination. |
| Callback verification | Keep signature verification in the callback route and use verifyQStashSignature() there. |
| Provider handle | The provider exposes sendBatch(), publish(), publishJSON(), schedules, messages, and urlGroups. |
Choose QStash when your queue flow is HTTP-first and callback verification matters as much as delivery.