Installation
JS SDK Reference
JS SDK Reference
bun
The @vercel/queue SDK lets JavaScript and TypeScript apps publish and consume Vercel Queues messages. For Python, see the Python SDK Reference.
Custom client
import { send, handleCallback } from'@vercel/queue';
Create a QueueClient when you need to target a specific region, set default options, or manage multiple clients.
TypeScript
Import the top-level helpers directly from @vercel/queue. A lazily-created default client resolves credentials from the Vercel environment.
import { QueueClient } from'@vercel/queue';
}
returnResponse.json({ messageId });
exportconst { send,handleCallback } = queue;
TypeScript
constqueue=newQueueClient({ region:'sfo1' });
import { send } from'@/lib/queue';
exportasyncfunctionPOST(request:Request) {
constbody=awaitrequest.json();
Then import from your module instead of @vercel/queue.
TypeScript
const { messageId } =awaitsend('orders', body);
awaitprocessOrder(message);
import { handleCallback } from'@/lib/queue';
TypeScript
});
exportconstPOST=handleCallback(async (message, metadata) => {
Use send to publish a message to a topic. The message can be any JSON-serializable value.
orderId:body.orderId,
exportasyncfunctionPOST(request:Request) {
constbody=awaitrequest.json();
TypeScript
const { messageId } =awaitsend('orders', {
});
}
action:'process',
returnResponse.json({ messageId });
import { send } from'@vercel/queue';
Although this Website may be linked to other websites, we are not, directly or indirectly, implying any approval.
region:'sfo1',
awaitsend('orders', payload, {
TypeScript
});
retentionSeconds:3600,
idempotencyKey:'order-123',
delaySeconds:60,
Option
Target a specific region for this message
retentionSeconds
Message TTL. Minimum 60 seconds, maximum 7 days (604,800 seconds)
Auto-detected
Default
Record
string
delaySeconds
Custom headers to include with this message
Type
Description
number
number
idempotencyKey
Delay before message becomes visible. Maximum 7 days, capped at message TTL
24 hours
string
Zero seconds
headers
Consuming messages in push mode
Use handleCallback to create a push mode consumer. Messages are automatically acknowledged when your handler completes, and retried if the handler throws.
For Express, Connect, or Next.js Pages Router apps, use handleNodeCallback instead, which accepts (req, res) arguments. Unlike the top-level exports, handleNodeCallback is only available on a QueueClient instance.
import { QueueClient } from'@vercel/queue';
First, configure the consumer in vercel.json.
exportdefaultqueue.handleNodeCallback(async (message, metadata) => {
"functions": {
});
awaitprocessOrder(message);
{
Then create the handler.
{ "type":"queue/v2beta","topic":"orders" }
"app/api/queues/process-order/route.ts": {
]
}
"experimentalTriggers": [
The metadata object includes:
exportconstPOST=handleCallback(async (message, metadata) => {
});
}
}
TypeScript
messageId
Number of times this message has been delivered
deliveryCount
Topic the message was published to
Type
string
Unique message identifier
number
createdAt
expiresAt
Date
Description
string
When the message expires
topicName
consumerGroup
string
Date
region
string
Handler options
Pass an options object as the second argument to handleCallback to configure visibility timeout and retry behavior.
Option
number
Default
5 minutes
Description
How long the message stays in-flight before redelivery
visibilityTimeoutSeconds
retry
function
-
Type
Custom retry logic. See custom retry behavior
},
exportconstPOST=handleCallback(
async (message, metadata) => {
visibilityTimeoutSeconds:600,
{
},
awaitprocessOrder(message);
Custom retry behavior
Queues API defaults to 60 seconds and does not auto-extend.
Control retry timing and handle poison messages with the retry option.
async (message, metadata) => {
import { handleCallback } from'@vercel/queue';
Return value
{ afterSeconds: number }
The retry callback can return:
Nitro v3 and frameworks built on it integrate with Vercel Queues through the Vercel preset. Declare topic triggers in nitro.config.ts, and Nitro generates the consumer function and trigger configuration during the build.
Behavior
Retry after the specified delay
undefined
{ acknowledge: true }
Acknowledge the message (stop retrying)
Use default retry behavior
vercel: {
queues: {
{
exportdefaultdefineConfig({
},
{ topic:'orders' },
topic:'notifications',
],
},
triggers: [
},
initialDelaySeconds:5,
retryAfterSeconds:60,
Option
exportdefaultdefinePlugin((nitro) => {
Each trigger accepts the following options:
nitro.hooks.hook('vercel:queue', ({ message, metadata }) => {
Description
Required
Topic to subscribe to
string
retryAfterSeconds
exportdefaultdefineHandler(async (event) => {
number
number
initialDelaySeconds
const { messageId } =awaitsend('orders', order);
});
});
return { messageId };
});
import {
UnauthorizedError,
try {
} catch (error) {
DuplicateMessageError,
QueueEmptyError,
// Invalid or expired token
} elseif (error instanceofDuplicateMessageError) {
MessageNotFoundError,
}
} from'@vercel/queue';
// Idempotency key collision
awaitsend('orders', payload);
if (error instanceofUnauthorizedError) {
transport:newStreamTransport(),
transport:newBufferTransport(),
constbinaryQueue=newQueueClient({
});
});
conststreamQueue=newQueueClient({
TypeScript
Our Services
Transport
Digital Marketing
BufferTransport
JsonTransport
Default. Serializes messages as JSON
Sends and receives raw binary data
Description
Related
Last updated August 12, 2026
StreamTransport
Sends and receives ReadableStream for large payloads
Cross-link map: Vercel Queues: JS SDK Reference (/docs/queues/sdk)From the Vercel docs graph (built 2026-09-21T05:26:59.511Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.jsonSemantically closest pagesQuickstart — Set up Vercel Queues with the SDK.Vercel Queues — Publish agent events and background work to durable topics with independent consumers, automatic retries, and at-least-oVercel Queues: Python SDK Reference — Publish and consume messages with the Vercel Queues Python SDK.Vercel Python Queues SDK is now available in betaPoll Mode — Consume messages from Vercel Queues by polling on your own schedule, from any environment.This page links to (4)Vercel Queues — Publish agent events and background work to durable topics with independent consumers, automatic retries, and at-least-oAPI Reference — HTTP API reference for Vercel Queues. Publish, consume, acknowledge, and manage messages.Poll Mode — Consume messages from Vercel Queues by polling on your own schedule, from any environment.Vercel Queues: Python SDK Reference — Publish and consume messages with the Vercel Queues Python SDK.Pages that link here (5)By site: vercel-docs (5)Vercel Queues — Publish agent events and background work to durable topics with independent consumers, automatic retries, and at-least-oQueues concepts — Learn delivery, retries, visibility timeouts, and deployment isolation in Vercel Queues.Queues Observability — Monitor queue throughput, message age, retries, and consumer performance to optimize your queue-based workflows.Vercel Queues: Python SDK Reference — Publish and consume messages with the Vercel Queues Python SDK.Quickstart — Set up Vercel Queues with the SDK.
