Quickstart

This guide shows how to send your first queue message and process it with the @vercel/queue 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 second route acts as a consumer. Vercel invokes it automatically in push mode.

• A Vercel account
• Vercel CLI installed (npm i -g vercel)
• Node.js 22+

1. Install the SDK

   Install @vercel/queue so your app can send messages and receive push callbacks.

   Terminal

   pnpm i @vercel/queue

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 calls to send and handleCallback 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 from @vercel/queue 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 with a route handler

   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 vercel.json

   Add a consumer trigger to wire your route to a topic. This makes the route private: it 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 handleCallback 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 (for example, during local development), it falls back to iad1.

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 next dev or vercel dev so you can test without deploying.

1. Installed the SDK: Added @vercel/queue to your project.
2. Created a producer: Published messages to the orders topic.
3. Configured a consumer: Registered a push trigger and handler to process messages.

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