By name: vercel-queues description: Build and operate Vercel Queues with @vercel/queue across push and poll consumers. Use when users ask about "vercel queues", "@vercel/queue", "queue/v2beta", "handleCallback", "PollingQueueClient", "receive", queue retries, visibility timeouts, idempotency keys, or queue region routing.
Implement queue producers and consumers using Vercel Queues docs and SDK contracts.
Step 1: Classify the request
Choose one path before writing code:
| Request type | Primary reference |
|---|---|
| First-time setup, minimal producer + consumer | references/quickstart.md |
| SDK usage, options, retries, transport behavior | references/sdk.md |
| API-level integration (custom clients, non-SDK consumers) | references/api.md |
| Delivery semantics and architecture decisions | references/concepts.md |
| Polling workers and mixed push/poll design | references/poll-mode.md |
| Local setup and debugging | references/local-dev.md |
If the task spans multiple categories, read only the relevant files above.
Step 2: Apply core guardrails
- Design consumers as idempotent because delivery is at-least-once.
- Pick push mode by default on Vercel unless the task explicitly needs scheduled/batched/client-driven polling.
- For poll mode, pin an explicit region and use the same region for send and receive.
- Use bounded retry strategy for poison messages (
acknowledge: trueafter threshold). - Keep topic and consumer names within
^[A-Za-z0-9_-]+$.
Step 3: Implement with minimal surface
- Prefer top-level
sendandhandleCallbackfor standard Vercel push mode. - Use
QueueClientonly when you need custom options (transport,token,headers,deploymentId). - Use
PollingQueueClientfor poll mode (receive) and handle{ ok: false, reason: "empty" }explicitly. - Keep
vercel.jsontrigger mapping explicit and scoped to the consumer route.
Step 4: Validate behavior
- Verify producer returns
messageIdand treat nullablemessageIdas acceptable deferred acceptance. - Verify consumer behavior across success, retry, and poison-message paths.
- Verify visibility timeout assumptions match workload duration.
- Verify region assumptions in poll mode.
Step 5: Troubleshoot from first principles
- Authentication issues: check OIDC/token source and env loading.
- Missing deliveries: verify topic name, trigger registration, and region alignment.
- Duplicate processing: verify idempotency key strategy and consumer idempotency.
- Backlog growth: inspect consumer throughput, retry policy, and visibility timeout.