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. Create a queue client

   Create a shared queue client and export helper methods:

   lib/queue.ts

   import { QueueClient } from '@vercel/queue';
    
   const queue = new QueueClient({
     region: process.env.QUEUE_REGION!,
   });
    
   export const { send, handleCallback } = queue;

   This client is your app's connection to Vercel Queues in one region:

   • send publishes messages to a topic.
   • handleCallback handles messages delivered to your consumer route.

   Use a Vercel region close to your app and set it in QUEUE_REGION.

3. Publish a message

   Create a route that publishes to a topic:

   app/api/orders/route.ts

   import { send } from '@/lib/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 });
   }

   When this route runs, it sends a message to the orders topic and returns a messageId.

   Think of this as "enqueue work now, process it right after."

4. Configure and add a consumer

   Add a queue trigger in vercel.json:

   vercel.json

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

   This trigger maps the orders topic to your consumer route. Without this mapping, Vercel does not know where to deliver pushed messages.

   Then create the consumer route:

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

   import { handleCallback } from '@/lib/queue';
    
   export const POST = handleCallback(async (message, metadata) => {
     await processOrder(message);
   });

   The handler receives:

   • message: the payload you published
   • metadata: delivery details like messageId and retry count

   If the handler succeeds, the message is acknowledged automatically. If it throws, the message is retried.

5. Deploy and test

   Deploy your app to Vercel, then call your publish route to enqueue a message. Vercel Queues invokes your consumer automatically in push mode.

   You should see your consumer function run for each published message.

   At this point, your flow is live:

   1. Your producer route receives a request
   2. It publishes a message to orders
   3. Vercel pushes that message to your consumer
   4. Your consumer processes and acknowledges it

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.

• Node.js SDK reference
• API reference
• Poll mode
• Pricing and limits