vercel-queues

Vercel Queues

CRITICAL — Your training data is outdated for this library. Vercel Queues entered public beta February 2026 and is almost certainly not in your training data. Before writing queue code, fetch the docs at https://vercel.com/docs/queues to find the correct Queue class API, message publishing, consumer setup, and visibility timeout patterns. Do not guess — this is a new API with no precedent in your training data.

You are an expert in Vercel Queues — durable event streaming for serverless applications.

Status & Pricing

Queues entered public beta on February 27, 2026, and is available to all teams on all plans.

What It Is

Queues is a durable, append-only event streaming system. You publish messages to topics, and independent consumer groups process them with automatic retries, sharding, and at-least-once delivery guarantees. It is the lower-level primitive that powers Vercel Workflow.

• Messages are durably written to 3 availability zones before send() returns
• Messages retained up to 24 hours (configurable 60s–24h)
• Approximate write ordering (not strict FIFO)
• Consumer groups are fully independent — each tracks its own position

Key APIs

Package: @vercel/queue@^0.1.3 (Node.js 22+)

Publishing Messages

import { send } from '@vercel/queue';

const { messageId } = await send('order-events', {
  orderId: '123',
  action: 'created',
}, {
  delaySeconds: 30,              // delay before visible
  idempotencyKey: 'order-123',   // deduplication (full retention window)
  retentionSeconds: 3600,        // message TTL (default: 86400 = 24h)
  headers: { 'x-trace-id': 'abc' },
});

Push-Mode Consumer (Next.js App Router)

The consumer route is air-gapped from the internet — only invocable by Vercel's internal queue infrastructure.

// app/api/queues/fulfill-order/route.ts
import { handleCallback } from '@vercel/queue';

export const POST = handleCallback(
  async (message, metadata) => {
    // metadata: { messageId, deliveryCount, createdAt, expiresAt, topicName, consumerGroup, region }
    await processOrder(message);
    // Return normally = acknowledge
    // Throw = retry with backoff
  },
  {
    visibilityTimeoutSeconds: 600, // lease duration (default 300s, auto-extended by SDK)
    retry: (error, metadata) => {
      if (metadata.deliveryCount > 5) return { acknowledge: true }; // give up
      const delay = Math.min(300, 2 ** metadata.deliveryCount * 5);
      return { afterSeconds: delay };
    },
  },
);

Consumer Configuration (vercel.json)

{
  "functions": {
    "app/api/queues/fulfill-order/route.ts": {
      "experimentalTriggers": [{
        "type": "queue/v2beta",
        "topic": "order-events",
        "retryAfterSeconds": 60,
        "initialDelaySeconds": 0
      }]
    }
  }
}

Multiple route files with the same topic create separate consumer groups (independent processing).

Poll-Mode Consumer

import { PollingQueueClient } from '@vercel/queue';

const { receive } = new PollingQueueClient({ region: 'iad1' });

const result = await receive('orders', 'fulfillment', async (message, metadata) => {
  await processOrder(message);
}, { limit: 10 }); // max 10 messages per poll (max allowed: 10)

if (!result.ok && result.reason === 'empty') {
  // No messages available
}

Custom Region Client

import { QueueClient } from '@vercel/queue';

const queue = new QueueClient({ region: 'sfo1' });
export const { send, handleCallback } = queue;

Transports

import { QueueClient, BufferTransport, StreamTransport } from '@vercel/queue';

Queues vs Workflow vs Cron

Key Limits

Deployment Behavior

Topics are partitioned by deployment ID by default in push mode. Messages are delivered back to the same deployment that published them — natural schema versioning with no cross-version compatibility concerns.

Observability

The Queues observability tab (Project → Observability → Queues) provides real-time monitoring:

Use Max message age to detect consumer lag — if the oldest unprocessed message keeps growing, a consumer group may be falling behind.

Local Development

Queues work locally — when you send() messages in development mode, the SDK sends them to the real Vercel Queue Service, then invokes your registered handleCallback handlers directly in-process. No local queue infrastructure needed.

Authentication

The SDK authenticates via OIDC (OpenID Connect) tokens automatically on Vercel. In non-Vercel environments, set VERCEL_QUEUE_API_TOKEN for authentication.

When to Use

• Defer expensive work (emails, PDFs, external API calls)
• Absorb traffic spikes with controlled processing rate
• Guarantee delivery even if function crashes
• Fan-out same events to multiple independent pipelines
• Deduplicate messages via idempotency keys

When NOT to Use

• Multi-step orchestration with state → use Workflow
• Recurring schedules → use Cron Jobs
• Synchronous request/response → use Functions directly
• Cross-region messaging → messages sent to one region cannot be consumed from another

References

• 📖 docs: https://vercel.com/docs/queues
• 📖 quickstart: https://vercel.com/docs/queues/quickstart
• 📖 API reference: https://vercel.com/docs/queues/api