Upstash QStash Queue
Configure Upstash QStash for queues and signed callback delivery.
Use Upstash QStash when you want 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/vite-hub/vitehub/@vitehub/queue@main @upstash/qstash
Configure Upstash QStash
nuxt.config.ts
export default defineNuxtConfig({
modules: ['@vitehub/queue/nuxt'],
queue: {
provider: 'qstash',
token: process.env.QSTASH_TOKEN!,
},
})
token is required. destination is required somewhere before runQueue() publishes to QStash: set a global queue.destination or set destination per queue.
If every queue shares the same callback URL, add a global default:
nuxt.config.ts
export default defineNuxtConfig({
modules: ['@vitehub/queue/nuxt'],
queue: {
provider: 'qstash',
token: process.env.QSTASH_TOKEN!,
destination: 'https://example.com/api/queues/welcome',
},
})
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/queues/welcome',
})
Verify callbacks
Use verifyQStashSignature() when your callback route should reject unsigned requests.
server/api/queues/welcome.post.ts
import { verifyQStashSignature } from '@vitehub/queue'
export default defineEventHandler(async (event) => {
const ok = await verifyQStashSignature(event.node.req as Request, {
currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY!,
nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY,
})
return { ok }
})
What changes on Upstash 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 Upstash QStash when your queue flow is HTTP-first and callback verification matters as much as delivery.