К основному содержанию
скилл CX Codex

queues — скилл для Claude Code: очереди Vercel

Скилл объясняет, как использовать Vercel Queues для фоновых задач, буферизации сообщений и доставки событий нескольким потребителям. Помогает выбрать между Queues и Workflows.

Apache-2.0 178 установок ★ 344 обновлён 2026-11-16

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add vercel/vercel-plugin --skill queues -a claude-code
Открыть на GitHub

Что делает queues

Скилл описывает темы сообщений Vercel Queues, группы потребителей и доставку с повторными попытками. Он подсказывает, когда очередь подходит для фоновой работы или распределения событий, а когда лучше выбрать Workflows для многошаговой логики с паузами и хуками.

В примерах используются send() из @vercel/queue, обработчик handleCallback() и регистрация потребителя в vercel.json через experimentalTriggers. Обработчик должен быть идемпотентным: одно сообщение может прийти повторно. Для локальной разработки сначала нужны vercel link и vercel env pull, иначе SDK не сможет пройти аутентификацию.

Какие задачи решает

  • отложить обработку фоновой задачи
  • распределить событие между группами потребителей
  • повторно обработать сообщение после ошибки
  • выбрать между Queues и Workflows

Примеры запросов агенту

  • Подскажи, как отправить фоновую задачу через Vercel Queues.
  • Покажи обработчик очереди с handleCallback() и настройку в vercel.json.
  • Сравни Queues и Workflows для обработки событий в несколько этапов.

Как установить queues

1Через Skills CLI (Vercel)

npx skills add vercel/vercel-plugin --skill queues -a claude-code

2Вручную: положить файлы

~/.claude/skills/queues/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/queues/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о queues

Как установить queues в Claude Code?

Выполните npx skills add vercel/vercel-plugin --skill queues -a claude-code. Файл скилла находится по пути ~/.claude/skills/queues/SKILL.md.

Что делает скилл queues?

Он помогает настроить Vercel Queues для фоновой обработки и доставки сообщений потребителям, а также выбрать между Queues и Workflows.

Что нужно для локальной разработки с Vercel Queues?

Перед локальной разработкой выполните vercel link и vercel env pull, чтобы SDK мог пройти аутентификацию. Обработчики должны учитывать повторную доставку сообщений.

Исходный текст

SKILL.md · Apache-2.0
---
name: queues
description: 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.
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'

---

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

```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 filename="vercel.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:

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

```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

© vercel · Apache-2.0 · vercel/vercel-plugin

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
vercel-queues официальный Vercel Labs Направляет агента при настройке Vercel Queues: публикации событий, push- и poll-обработчиков и vercel.json. Используется для асинхронных задач в Node.js 22+. CX Codex GP ChatGPT +1 6установок laravel-queues agent-skills Скилл laravel-queues помогает проектировать асинхронные задачи, настраивать Horizon, отлаживать застрявшие джобы и проверять здоровье очереди в Laravel 13. CX Codex +1 770установок inngest-brownfield-audit inngest Скилл inngest-brownfield-audit разбирает существующий TypeScript- или JavaScript-проект и показывает, где фоновая работа теряется при деплое или падении процесса. CX Codex +1 734установок dbos-python dbos Справочник по DBOS Python 3.x для агента: воркфлоу и шаги, очереди, расписания, DBOSClient и переезд с 2.x без устаревших вызовов. CX Codex +1 880установок python-background-jobs Seth Hobson Скилл python-background-jobs для Claude Code выносит долгие Python-задачи из цикла запрос–ответ и обрабатывает их воркерами. Решает задачи очередей, экспортов, уведомлений и событийной архитектуры. CX Codex +1 11 137установок queue-job-processor patricio0312rev Скилл queue-job-processor настраивает фоновые очереди задач на базе BullMQ и Redis, включая воркеры, повторные попытки и отслеживание прогресса. CX Codex +1 300установок

Из того же набора9

access-protected-vercel-deployment Скилл access-protected-vercel-deployment объясняет агенту, как ходить в деплои Vercel за Vercel Authentication и SSO: через vercel curl или короткоживущий OIDC-токен в заголовке. CX Codex +1 2 600установок build-agents Скилл build-agents задаёт правила создания ИИ-агентов на базе фреймворка eve от Vercel. Помогает развернуть проект, настроить инструменты и фоновые задачи. CX Codex +1 1 500установок create-a-backend Скилл create-a-backend подбирает архитектуру бэкенда на платформе Vercel под конкретные задачи проекта. Он помогает определиться с компонентами до написания кода реализации. CX Codex +1 708установок vercel-schedules Помогает настроить запуск функций по расписанию в Vercel Schedules. Включается при добавлении cron-задач, фоновых процессов и разовых напоминаний. CX Codex +1 183установок custom-metrics Скилл custom-metrics для Claude Code настраивает отправку числовых метрик из Vercel Functions. Агент встраивает вызовы функции metric() при создании или редактировании серверных обработчиков. CX Codex +1 148установок domains Скилл domains для Claude Code ищет домены и управляет регистрацией через инструменты Vercel. Он подключается к задачам с поиском домена, DNS, переносом или продлением. CX Codex +1 143установок is-agentic Скилл is-agentic для Claude Code оценивает готовность сайта, домена или публичного MCP-эндпоинта к работе с ИИ-агентами. Агент запускает проверку, читает отчёт или разбирает найденные проблемы. CX Codex +1 108установок vercel Плагин vercel для Claude Code помогает управлять развёртываниями Vercel, проверять сборки и смотреть логи. Он подключается к задачам с проектами, доменами и инфраструктурой Vercel. ★ 344звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой