Queue runtime API

Reference for defineQueue, runQueue, deferQueue, getQueue, and the core Queue types.

Use this page when you need the Queue surface area, signatures, or option names. For a guided first run, start with Quickstart.

Definition APIs

`defineQueue(handler, options?)`

Use defineQueue() to register one queue definition from the discovery directory.

Queue definitions live in server/queues/**.

import { defineQueue } from '@vitehub/queue'

export default defineQueue(async (job) => {
  return {
    id: job.id,
  }
}, {
  cache: false,
})

`createQueue(options?)(handler)`

createQueue() is not the normal Nitro or Nuxt definition pattern. Use defineQueue() there.

Enqueue APIs

`runQueue(name, input)`

Use runQueue() for the normal enqueue path.

You can pass either:

a bare payload for the common case
an input object when you need delivery options

import { runQueue } from '@vitehub/queue'

await runQueue('welcome-email', {
  email: 'ava@example.com',
})

await runQueue('welcome-email', {
  id: 'welcome-1',
  payload: { email: 'ava@example.com' },
  delaySeconds: 10,
})

`deferQueue(name, input)`

Use deferQueue() when the send should happen after the current response is already committed.

deferQueue() reads the active request context. It uses waitUntil() when the runtime provides it and falls back to fire-and-forget dispatch otherwise.

import { deferQueue } from '@vitehub/queue'

export default defineEventHandler(() => {
  deferQueue('welcome-email', {
    email: 'ava@example.com',
  })

  return { ok: true }
})

Use Defer after response when you need the request-context rules in more detail.

Enqueue input options

These options are available when you pass an object to runQueue() or deferQueue():

Option	Description
`payload`	The message payload passed to the queue handler.
`id`	Override the generated job identifier.
`maxAttempts`	Request retry attempts when the provider supports them.
`resultTTL`	Keep job results for a limited time when the provider supports it.
`timeout`	Set an execution or wait timeout when the provider supports it.
`idempotencyKey`	Deduplicate sends when the provider supports it.
`retentionSeconds`	Keep the queued message for a limited time when the provider supports it.
`delaySeconds`	Delay delivery by a number of seconds.
`delayUntil`	Delay delivery until a specific time when the provider supports it.
`priority`	Request provider-specific priority handling.
`contentType`	Override how the payload is encoded when the provider supports it.

Option support varies by provider. Use the provider pages for exact behavior.

Queue handle API

`getQueue(name?)`

Use getQueue() when you need the active queue handle instead of a send call.

import { getQueue } from '@vitehub/queue'

const queue = await getQueue('welcome-email')

console.log(queue.provider)

Most apps only need runQueue(). Reach for getQueue() when you need provider-native methods such as batch handlers, polling helpers, or direct inspection tools.

Use Native handles for guidance on when to cross that boundary.

Validation helpers

Queue also exports validation helpers for enqueue routes and handlers:

Helper	Use it for
`readValidatedPayload()`	Validate user input before enqueueing.
`readValidatedJob()`	Validate the payload inside the queue handler.

Use Validate payloads for examples.

Core types

`QueueJob<TPayload>`

Queue handlers receive a QueueJob<TPayload> object.

Field	Type	Description
`id`	`string`	Unique job identifier.
`payload`	`TPayload`	The payload you enqueued.
`attempts`	`number`	The current attempt count.
`signal`	`AbortSignal`	Abort signal tied to the job lifecycle.

`QueueDefinitionOptions`

QueueDefinitionOptions combines portable queue behavior with provider-specific overrides.

Option	Description
`cache`	Enable or disable client caching for this queue definition.
`concurrency`	Limit concurrent processing when the provider supports it.
`onError`	Handle queue message failures.
`callbackOptions`	Per-queue Vercel callback settings.
`consumer`	Override the Vercel consumer name.
`config`	Pass Netlify Async Workloads handler config.
`destination`	Override the Upstash QStash callback destination.

Report an issue or Edit this page on GitHub

Quickstart

Get a first queue working locally with the memory provider.

When to use Queue

Decide when Queue is the right primitive compared with Workflow, Cron, or inline request handling.