Queues Lab

cd apps/experiments/queues-lab
pnpm install
pnpm dev

The Queues Lab demonstrates Vercel Queues (public beta): durable topics, fan-out consumer groups, and at-least-once delivery with retries. Producers call send() from @vercel/queue. A private consumer uses handleCallback and is registered with experimentalTriggers type queue/v2beta in vercel.json.

FeaturesCopy Anchor Link

• Live publish. POST /api/queues/publish with mode: "live" calls send('experiments-orders', payload).
• Private fulfill consumer. app/api/queues/fulfill/route.ts records processed messages when Queues invokes it.
• Simulator mode. In-memory fan-out across fulfillment and analytics groups, plus idempotency-key dedupe, for local learning without OIDC.
• Honest errors. Missing OIDC returns 503 with setup requirements instead of inventing message ids.

API ReferenceCopy Anchor Link

POST /api/queues/publishCopy Anchor Link

GET /api/queues/publishCopy Anchor Link

Returns the topic name, recent processed entries, and simulator backlog.

Consumer (POST fulfill)Copy Anchor Link

Configured only via Queues push - not a public webhook:

{
  "functions": {
    "app/api/queues/fulfill/route.ts": {
      "experimentalTriggers": [
        { "type": "queue/v2beta", "topic": "experiments-orders" }
      ]
    }
  }
}

Implementation DetailsCopy Anchor Link

Producer (live path):

const { send } = await import('@vercel/queue');
const result = await send(QUEUE_TOPIC, payload, idempotencyKey
  ? { idempotencyKey }
  : undefined);

Consumer:

export const POST = handleCallback(async (order, metadata) => {
  recordProcessed({
    messageId: metadata.messageId,
    orderId: order.orderId ?? 'unknown',
    receivedAt: new Date().toISOString(),
    source: 'queue-callback',
  });
});

TopicSimulator in logic.ts models fan-out and retry/expire behaviour for the educational path.

Use CasesCopy Anchor Link

• Offload email, PDF, or provider calls after a fast HTTP response
• Absorb traffic spikes with buffered processing
• Fan out one event stream to independent pipelines (analytics vs fulfillment)

LimitationsCopy Anchor Link

• Queues is in public beta; APIs and limits can change.
• Live mode needs OIDC (vercel link + vercel env pull) or a Vercel deployment.
• The in-memory log resets on cold start - it is not durable storage.
• Prefer Workflows when you need multi-step durable orchestration with sleep/hooks.

Use in your projectCopy Anchor Link

1. pnpm add @vercel/queue
2. Publish with send(topic, payload)
3. Add a handleCallback route and experimentalTriggers in vercel.json
4. Keep handlers idempotent

DeploymentCopy Anchor Link

Deploy on Vercel

After deploy, publish with the UI (live mode) or curl, then check Observability - Queues and the recent-processed list in the demo.

Local DevelopmentCopy Anchor Link

cd apps/experiments/queues-lab
pnpm install
vercel link && vercel env pull
pnpm dev

Use simulator mode without OIDC. Unit tests:

pnpm vitest run ../experiments/queues-lab

ConfigurationCopy Anchor Link

Vercel / Next.js Features UsedCopy Anchor Link

• Vercel Queues
• @vercel/queue SDK (send, handleCallback)
• Next.js Route Handlers
• Function experimentalTriggers

Next StepsCopy Anchor Link