Enqueue a job

This guide defines a welcome-email queue, then calls it from a server route. It assumes Queue is already registered in Vite or Nitro config.

Define the queue

Create one queue definition with the payload shape the producer will send.

import { defineQueue } from '@vitehub/queue'

export type WelcomeEmailPayload = {
  email: string
  template: 'default' | 'vip'
}

export default defineQueue<WelcomeEmailPayload>(async (job) => {
  console.log(`Send ${job.payload.template} welcome email to ${job.payload.email}`)
})

Call pattern

Every producer follows the same shape:

1. Read or build a payload.
2. Call runQueue(name, payload).
3. Return the QueueSendResult.

import { H3, readBody } from 'h3'
import { runQueue } from '@vitehub/queue'
import type { WelcomeEmailPayload } from './welcome-email.queue'

const app = new H3()

app.post('/api/welcome', async (event) => {
  const payload = await readBody<WelcomeEmailPayload>(event)
  const result = await runQueue('welcome-email', payload)

  return { ok: true, result }
})

export default app

Add delivery options

Use an enqueue envelope when the send needs provider options:

const result = await runQueue('welcome-email', {
  id: 'welcome-email-1',
  payload: {
    email: 'ava@example.com',
    template: 'vip',
  },
  delaySeconds: 30,
})

Keep provider-specific fields out of shared helper code unless the helper is intentionally provider-specific.

Defer the enqueue call

Use deferQueue() when the route does not need the queued result:

import { deferQueue } from '@vitehub/queue'

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

  return { ok: true }
})

The runtime uses waitUntil() when available, so the response can finish while the enqueue promise continues.

Verify the route

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

Expected response:

{
  "ok": true,
  "result": {
    "status": "queued",
    "messageId": "queue_7f1b6f8e-7b5c-4c5e-b3a1-8d6a4b3d4c2a"
  }
}

Avoid these mistakes