Queue

Send queue jobs through Platformatic, Cloudflare, Vercel, Netlify, or QStash.

Queue moves work out of the current request. Queue fits tasks that should be retried, delayed, rate limited, retained, or processed by a provider-native queue instead of running inline.

ViteHub discovers queues from server/queues/**.

Define a queue with createQueue(options?)(handler) or defineQueue(handler, options?), then enqueue work with runQueue().

Getting started

Install the package

Terminal

pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/queue@main @platformatic/job-queue

Terminal

pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/queue@main

Terminal

pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/queue@main @vercel/queue

Terminal

pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/queue@main @netlify/async-workloads

Terminal

pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/queue@main @upstash/qstash

Terminal

pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/queue@main

Memory processes jobs in-process. The memory provider does not require an extra npm package.

Configure a provider

Hosted presets infer Cloudflare, Vercel, and Netlify automatically. Set queue.provider for Platformatic, QStash, or explicit overrides.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@vitehub/queue/nuxt'],
  queue: {
    provider: 'platformatic',
  },
})

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@vitehub/queue/nuxt'],
})

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@vitehub/queue/nuxt'],
})

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@vitehub/queue/nuxt'],
})

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',
  },
})

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@vitehub/queue/nuxt'],
  queue: {
    provider: 'memory',
  },
})

Define a queue

Create a queue in server/queues/**. The file name becomes the queue name.

server/queues/welcome-email.ts

import { createQueue } from '@vitehub/queue'

export default createQueue({
  cache: false,
})(async (job) => {
  return {
    id: job.id,
    queued: true,
    payload: job.payload,
  }
})

Send a message

Import runQueue() from @vitehub/queue and pass the queue name with a payload.

server/api/queue/welcome.post.ts

import { readBody } from 'h3'
import { runQueue } from '@vitehub/queue'

export default defineEventHandler(async (event) => {
  const body = await readBody<{ email?: string }>(event)

  return runQueue('welcome-email', {
    id: `welcome-${Date.now()}`,
    payload: {
      email: body.email,
    },
  })
})

Reach for the native handle only when you need it

Most apps only need runQueue(). Use getQueue() when you need provider-native methods such as batch sends, polling clients, or signature helpers.

server/api/queue/status.get.ts

import { getQueue } from '@vitehub/queue'

export default defineEventHandler(async () => {
  const queue = await getQueue('welcome-email')

  return {
    provider: queue.provider,
  }
})

Platformatic Queue

Configure Platformatic Job Queue with local or self-hosted workers.

Cloudflare Queue

Configure Cloudflare Queues and process named queues in Workers.

Vercel Queue

Configure Vercel Queue and send named jobs through Vercel.

Netlify Queue

Configure Netlify Async Workloads and run named queues on Netlify.

QStash Queue

Configure Upstash QStash for queues and signed callback delivery.

Memory Queue

Process queue jobs in-memory for local development and testing.

Public API

Function	Use it for

| createQueue(options?)(handler) | Register one named queue under server/queues/**. |

| defineQueue(handler, options?) | Register one named queue with the direct (handler, options?) form. | | runQueue(name, { id?, payload, ...options }) | Enqueue work without using the provider-native client directly. | | getQueue(name?) | Resolve the provider-native queue handle when you need advanced methods. |

Type reference

`QueueJob<TPayload>`

The handler receives a QueueJob object with these fields:

Field	Type	Description
`id`	`string`	Unique job identifier, set when enqueuing.
`payload`	`TPayload`	The data you passed to `runQueue()`.
`attempts`	`number`	How many times the job has been attempted.
`signal`	`AbortSignal`	Abort signal tied to the job timeout.

The handler can return any value or nothing at all. ViteHub does not enforce a return type.

`QueueDefinitionOptions`

The options object passed to createQueue() or the second argument to defineQueue() combines portable queue behavior with the provider-specific overrides that ViteHub wires directly:

Option	Type	Description
`cache`	`boolean`	Enable or disable client caching for this queue. Defaults to `true`.
`callbackOptions`	`VercelQueueCallbackOptions`	Per-queue Vercel callback settings forwarded to `queue.callback()`.
`concurrency`	`number`	Maximum parallel message processing.
`config`	`NetlifyAsyncWorkloadConfig`	Per-queue Netlify Async Workloads handler config forwarded to `queue.createHandler()`.
`consumer`	`string`	Per-queue Vercel consumer name. Defaults to `"default"`.
`destination`	`string`	Per-queue QStash callback destination that overrides `queue.destination`.
`onError`	`(error, message) => void`	Called when a message fails.

Signature verification and other route-level concerns stay outside queue definitions. Use verifyQStashSignature() in the callback route that receives QStash requests.

How configuration works

Queue has one global layer and one queue-local layer:

Top-level queue config in nitro.config.ts selects the provider and sets app-wide integration defaults.
createQueue(options?)(handler) and defineQueue(handler, options?) configure one queue definition with portable behavior plus the provider-specific overrides ViteHub owns for Vercel, Netlify, and QStash.

runQueue() is the enqueue call. Pass the message payload and delivery options for one send. getQueue() resolves the provider-native handle when you need advanced methods.

nitro.config.ts

export default defineNitroConfig({
  queue: {
    provider: 'platformatic',
  },
})

server/queues/welcome-email.ts

export default createQueue({
  cache: false,
})(async (job) => {
  return {
    email: job.payload?.email,
  }
})

Each provider adds its own queue APIs and sub-features. Use the provider pages in the sidebar for storage setup, callback helpers, signature verification, and provider-only runtime methods.ViteHub only requires an extra SDK for the provider you choose. Cloudflare and memory stay SDK-free.

Report an issue or Edit this page on GitHub

Vercel

Generate Vercel cron config from discovered crons.

Platformatic

Configure Platformatic Job Queue with local or self-hosted workers.