Index of every page on this site: llms.txt
All skills
vercel avatar

/queues

@250769d official
by vercelvercel/vercel-plugin340 stars
82
Run it yourself

Vercel Queues guidance — durable topics with at-least-once delivery, independent consumer groups, retries, delays, and idempotency keys via @vercel/queue (JS) or vercel-queue (Python). Use when deferring background work, buffering traffic, fanning out events, or choosing between Queues and Workflows.

Use this Skill: https://skilld.dev/gh/vercel/vercel-plugin/queues

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈78 tokens for metadata: the name and description. ≈1.7k when used: this file.

Description uses 3.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈310 characters, or 3.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Vercel Queues

You are an expert in Vercel Queues, the durable message topics that power background work and agent events on Vercel.

What It Is

Vercel Queues (public beta) gives you durable, append-only topics. Producers publish JSON messages, and every subscribed consumer group receives every message with at-least-once delivery and automatic retries. New consumer groups can join later and replay non-expired history. Queues is the primitive under Vercel Workflows; use Queues directly when you need control over publishing, consumption, and routing.

  • Topic: a named durable log of messages, created on first publish
  • Consumer group: an independent subscriber that receives every message on a topic
  • Delivery: at-least-once; handlers must be idempotent
  • Retention: 24 hours by default, up to 7 days; delivery can be delayed up to the retention period
  • Modes: push (Vercel invokes your function) or poll (your own workers pull messages from any environment)

Choose Queues or Workflows

Need Use Why
Fire-and-forget background job, fan-out, buffering Queues Direct publish/consume, independent consumer groups
Multi-step logic with sleep, hooks, or human approval Workflows (⤳ skill: workflow) Durable steps and replay built on top of Queues
Scheduled invocation on a cron or once at a set time Vercel Schedules (⤳ skill: vercel-schedules); a schedule can publish to a queue topic Time-based trigger, not message-based; beta, replaces legacy Cron Jobs

Quickstart (Next.js App Router)

Install the SDK:

npm install @vercel/queue

Publish from any route, Server Action, or function:

// app/api/orders/route.ts
import { send } from '@vercel/queue';

export async function POST(request: Request) {
  const body = await request.json();
  const { messageId } = await send('orders', { orderId: body.orderId, action: 'process' });
  return Response.json({ messageId });
}

Consume with a push-mode handler. Messages are acknowledged when the handler returns and retried when it throws:

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

export const POST = handleCallback(async (message, metadata) => {
  await processOrder(message);
  console.log('processed', metadata.messageId, 'delivery', metadata.deliveryCount);
});

Register the consumer in vercel.json (or vercel.ts) so Vercel routes the topic to that function:

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

Run vercel link and vercel env pull before local development so the SDK can authenticate.

Send Options

await send('orders', payload, {
  region: 'sfo1',            // target a specific region
  retentionSeconds: 3600,    // message TTL; min 60, max 604800 (7 days); default 24 hours
  delaySeconds: 60,          // delay first delivery; max 7 days, capped at the TTL
  idempotencyKey: 'order-123', // duplicates within min(retention, 24 hours) are dropped
  headers: { 'x-trace-id': 'abc-123' },
});

Create a QueueClient when you need defaults, a fixed region, or multiple clients:

// lib/queue.ts
import { QueueClient } from '@vercel/queue';

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

Consumer Options and Retries

handleCallback(handler, options) accepts:

Option Default Notes
visibilityTimeoutSeconds 300 How long a message stays in flight; the SDK re-extends the lease while the handler runs
retry trigger retryAfterSeconds (60s) (error, metadata) => { afterSeconds } | { acknowledge: true } | undefined

Handle poison messages by acknowledging after a delivery-count threshold:

export const POST = handleCallback(processOrder, {
  retry: (error, metadata) => {
    if (metadata.deliveryCount > 5) return { acknowledge: true }; // stop retrying
    return { afterSeconds: Math.min(300, 2 ** metadata.deliveryCount * 5) };
  },
});

metadata includes messageId, deliveryCount, createdAt, expiresAt, topicName, consumerGroup, and region.

For Express, Connect, or Next.js Pages Router handlers use queue.handleNodeCallback(async (message, metadata) => ...) from a QueueClient instance, which takes (req, res).

Other Runtimes and Frameworks

  • Python: vercel-queue publishes and consumes with the same topic model, and FastAPI, Flask, and Django apps can use it; Celery and Dramatiq integrations are documented under the Python backend frameworks.
  • Nitro / Nuxt: declare vercel.queues.triggers in nitro.config.ts and handle messages with the vercel:queue runtime hook; send from @vercel/queue works in any server route.
  • Poll mode: pull messages from your own workers in any environment when push delivery to a Vercel Function does not fit. On Vercel, run an always-on poll-mode consumer as a daemon (⤳ skill: daemons).
  • Payloads: JSON by default; use BufferTransport for binary or StreamTransport for large bodies when constructing a QueueClient.

Errors

@vercel/queue exports typed errors: UnauthorizedError, BadRequestError, and MessageNotFoundError. QueueEmptyError is exported but never thrown; an empty poll-mode receive returns { ok: false, reason: 'empty' }. Duplicate idempotency keys do not throw; the duplicate is silently dropped.

Common Pitfalls

  1. Missing trigger: a handleCallback route with no experimentalTriggers entry never receives messages. Register every consumer in vercel.json/vercel.ts.
  2. Non-idempotent handlers: delivery is at-least-once. Key side effects on metadata.messageId or your own idempotencyKey.
  3. Retrying forever: without a retry policy that acknowledges poison messages or a trigger maxDeliveries cap, a permanently failing message is redelivered until it expires.
  4. Using Queues for multi-step logic: if you need sleep, hooks, or approvals between steps, use Workflows instead of chaining topics by hand.
  5. Local dev without credentials: run vercel link and vercel env pull first; otherwise send() throws Failed to get OIDC token for local development.

References

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning9d3 checks · Risk SAFE
  • Gen Agent Trust Hub10d

    This skill provides guidance on using Vercel Queues for background job processing and event streaming. It utilizes official Vercel SDKs and follows established developer workflows for the Vercel platform. No security concerns were identified during the analysis.

  • Socket9d

    No alerts

  • Snyk10d

    Risk: MEDIUM · 1 issue

Signed by skilld at 250769d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 weeks ago
Other metadata
summary
Vercel Queues (beta) publishes JSON messages to durable topics with `send()` from `@vercel/queue`; consumers are Vercel Functions exported with `handleCallback()` and registered in vercel.json under `functions.<path>.experimentalTriggers` as `{ type: 'queue/v2beta', topic: '<name>' }`. Delivery is at-least-once with automatic retries; use Workflows instead for multi-step durable logic.
metadata
{
  "priority": 6,
  "docs": [
    "https://vercel.com/docs/queues",
    "https://vercel.com/docs/queues/sdk"
  ],
  "sitemap": "https://vercel.com/sitemap.xml",
  "pathPatterns": [
    "app/api/queues/**",
    "src/app/api/queues/**",
    "pages/api/queues/**",
    "lib/queue.*",
    "src/lib/queue.*",
    "lib/queues/**",
    "src/lib/queues/**"
  ],
  "bashPatterns": [
    "\\bnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/queue\\b",
    "\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/queue\\b",
    "\\bbun\\s+(install|i|add)\\s+[^\\n]*@vercel/queue\\b",
    "\\byarn\\s+add\\s+[^\\n]*@vercel/queue\\b",
    "\\b(pip|uv)\\s+(install|add)\\s+[^\\n]*vercel-queue\\b"
  ],
  "importPatterns": [
    "@vercel/queue"
  ],
  "promptSignals": {
    "phrases": [
      "vercel queues",
      "@vercel/queue",
      "background job",
      "background jobs",
      "message queue",
      "job queue",
      "consumer group"
    ],
    "allOf": [
      [
        "vercel",
        "queues"
      ],
      [
        "queue",
        "topic"
      ],
      [
        "queue",
        "consumer"
      ],
      [
        "queue",
        "buffer"
      ],
      [
        "fan",
        "out"
      ]
    ],
    "anyOf": [
      "queue",
      "topic",
      "retry",
      "consumer",
      "buffer",
      "background"
    ],
    "noneOf": [
      "build queue",
      "deployment queue",
      "queued deployment",
      "deployments stuck",
      "queues up deployments",
      "queue up deployments",
      "queues my deployments",
      "queues our deployments",
      "queues your deployments",
      "queues the deployments",
      "queues deployments",
      "queues builds",
      "queues my builds"
    ],
    "minScore": 6
  }
}
retrieval
{
  "aliases": [
    "queues",
    "message queue",
    "background jobs",
    "event streaming",
    "pub sub"
  ],
  "intents": [
    "defer work to a queue",
    "process background jobs",
    "fan out events to consumers",
    "retry failed jobs",
    "buffer traffic spikes"
  ],
  "entities": [
    "Vercel Queues",
    "@vercel/queue",
    "topic",
    "consumer group",
    "handleCallback",
    "experimentalTriggers"
  ]
}
chainTo
[
  {
    "pattern": "\"use workflow\"|\"use step\"|from\\s+['\"]workflow['\"]",
    "targetSkill": "workflow",
    "message": "Workflow SDK code alongside Queues — Workflows is built on Queues and adds durable steps, sleep, and hooks. Loading Workflow guidance."
  },
  {
    "pattern": "from\\s+['\"](bullmq|bull|bee-queue|agenda)['\"]|@aws-sdk/client-sqs",
    "targetSkill": "queues",
    "message": "Third-party job queue detected — Vercel Queues provides durable topics with retries and fan-out without running a broker. Loading Queues guidance.",
    "skipIfFileContains": "@vercel/queue"
  }
]

README badge

README badge for vercel/vercel-plugin/queues