vercel/vercel-plugin

queues

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).

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/vercel/vercel-plugin --skill queues

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

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

NeedUseWhy
Fire-and-forget background job, fan-out, bufferingQueuesDirect publish/consume, independent consumer groups
Multi-step logic with sleep, hooks, or human approvalWorkflows (⤳ skill: workflow)Durable steps and replay built on top of Queues
Scheduled invocation on a cron or once at a set timeVercel Schedules (⤳ skill: vercel-schedules); a schedule can publish to a queue topicTime-based trigger, not message-based; beta, replaces legacy Cron Jobs

Quickstart (Next.js App Router)

Install the SDK:

bash
npm install @vercel/queue

Publish from any route, Server Action, or function:

ts
// 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:

ts
// 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:

json
{
  "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

ts
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:

ts
// 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:

OptionDefaultNotes
visibilityTimeoutSeconds300How long a message stays in flight; the SDK re-extends the lease while the handler runs
retrytrigger retryAfterSeconds (60s)`(error, metadata) => { afterSeconds } \{ acknowledge: true } \undefined`

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

ts
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

  • 📖 docs: https://vercel.com/docs/queues
  • 📖 JS SDK: https://vercel.com/docs/queues/sdk
  • 📖 Python SDK: https://vercel.com/docs/queues/python-sdk
  • 📖 poll mode: https://vercel.com/docs/queues/poll-mode
  • 📖 pricing and limits: https://vercel.com/docs/queues/pricing
aus demselben Repository

Weitere Skills

Alle Skills
vercel
Offiziell

access-protected-vercel-deployment

Access and test Vercel deployments protected by Vercel Authentication, SSO, or Deployment Protection. Use when curl, agent-browser, Playwright, or another automated request reaches a Vercel login or protection page; when a protected preview or production URL returns 401 or 403; when TRUSTEDSOURCESENVIRONMENTMISMATCH appears; or when choosing between vercel curl and the x-vercel-trusted-oidc-idp-token header.

Installationen / 1h
1
GitHub Stars
341
Aktualisiert
20. Nov.
vercel
Offiziell

client-side-security

Protect what runs in your users' browsers on Vercel with a Content-Security-Policy header and Page Integrity script monitoring. Use when adding or debugging a CSP, choosing where to set it (Next.js proxy.ts or next.config.js, vercel.json, Project Routes), allowing Vercel Toolbar under CSP, monitoring third-party scripts or tag managers, or meeting PCI DSS script requirements. For WAF rules and rate limits use vercel-firewall; for bots use botid.

Installationen / 1h
1
GitHub Stars
341
Aktualisiert
20. Nov.
vercel
Offiziell

domains

Search, register, connect, transfer, and renew domain names on Vercel using the CLI or Domains Registrar API. Use for domain availability and pricing, custom domains, DNS records, nameservers, ownership verification, and domain orders.

Installationen / 1h
1
GitHub Stars
341
Aktualisiert
20. Nov.
vercel
Offiziell

vercel-schedules

Vercel Schedules guidance — run a private function, route, or Vercel Queues topic on a cron cadence or once at a set time. Covers static schedules in vercel.json, dynamic per-user schedules with @vercel/schedules, handleSchedule, the vercel schedules CLI, environments, jitter, and migrating from Cron Jobs. Use when adding scheduled or recurring work, one-time reminders, or replacing crons.

Installationen / 1h
1
GitHub Stars
341
Aktualisiert
20. Nov.