Quickstart

This guide shows how to send your first queue message and process it with the Vercel Queues SDK.

In this quickstart:

• Your API route acts as a producer. It sends work to a queue topic.
• The topic (orders) stores messages durably until a consumer processes them.
• A consumer processes the message. Vercel invokes it automatically in push mode.

• A Vercel account
• Vercel CLI installed (npm i -g vercel)
• Node.js 22+ for Node.js apps, or Python 3.12+ for Python apps

1. Install the SDK

   Install the SDK so your app can send messages and receive push callbacks.

   pnpmyarnnpmbunuvpip

   Terminal

   pnpm i @vercel/queue

   Terminal

   yarn add @vercel/queue

   Terminal

   npm i @vercel/queue

   Terminal

   bun add @vercel/queue

   Terminal

   uv add vercel

   Terminal

   pip install vercel

2. Link your Vercel project and pull credentials

   The SDK authenticates via OIDC. Link your project if you haven't already, then pull environment variables so the SDK can authenticate during local development:

   Terminal

   vercel link
   vercel env pull

   This creates a .env.local file containing the OIDC tokens the SDK needs to connect to Vercel Queues from your machine. Without it, local SDK calls can't authenticate. When you deploy to Vercel, authentication is automatic and no environment setup is needed.

3. Send a message anywhere in your app

   Import send directly and call it from any server-side context: a route handler, a Server Action, a Workflow step, or an error handler.

   app/cart/checkout/route.ts

   import { send } from '@vercel/queue';
    
   export async function POST(request: Request) {
     const order = await request.json();
     const { messageId } = await send('orders', order);
     return Response.json({ messageId });
   }

4. Handle incoming messages

   app/api/queues/fulfill-order/route.ts

   import { handleCallback } from '@vercel/queue';
    
   export const POST = handleCallback(async (order, metadata) => {
     // await chargePayment(order);
     // await sendConfirmationEmail(order);
     console.log('Fulfilling order', metadata.messageId, order);
   });

5. Configure the consumer

   For JavaScript and TypeScript, add a consumer trigger to vercel.json. For Python, set entrypoint in pyproject.toml to the subscriber's Python module import path. For example, use queues.orders for the module at queues/orders.py. The Python build imports the module, reads the @subscribe configuration, and generates the queue-triggered function.

   Both configurations make the consumer private. The consumer has no public URL, and only Vercel's queue infrastructure can invoke it.

   vercel.json

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

The top-level send and callback helpers use an auto-configured default client. The region is detected from the VERCEL_REGION environment variable, which Vercel sets on every deployment. If the region can't be detected, the Node.js SDK falls back to iad1. In Python, pass region or set VERCEL_REGION when you run outside Vercel. Python send() chooses the serializer from the payload type, including Pydantic models through model_dump_json().

To target a specific region when sending, pass the region option:

await send('orders', payload, { region: 'sfo1' });

If your handler crashes after charging payment but before sending the email, Vercel redelivers the message so the email still goes out. If the email call fails, the message comes back and your handler runs again. Make each step idempotent (for example, pass an idempotency key to your payment provider) so retries are safe.

This works locally with vercel dev so you can test without deploying. Next.js projects can also use next dev.

1. Installed the SDK: Added the Vercel Queues package for your language.
2. Created a producer: Published messages to the orders topic.
3. Configured a consumer: Registered a private push consumer to process messages.

• JS SDK reference
• Python SDK reference
• API reference
• Poll mode
• Pricing and limits