Queues

Whilst building a webapp you want to be able to respond as quickly as possible to user interactions, but sometimes you need to do things that take a long time! For example, you might need to send an email when a user submits a form, or you need to process a payment, or do something magic with AI - and you don’t want the user to wait for these things to complete.

To handle these you’ll use background tasks. Background tasks are managed by the Cloudflare queue system. You send a message to a queue, where a worker will process the message, but on a different worker - so it doesn’t block the main one.

Pick your poison

You do not need to use Cloudflare’s queue system, you can use any background task system you want, but we recommend using queues!

Setup

First thing you’ve got to do is create a queue and bind the queue producers and consumers to your worker.

npx wrangler queues create MY_QUEUE_NAME

Replace "MY_QUEUE_NAME" with the name of your queue, and place the following in your wrangler.jsonc file:

wrangler.jsonc

{
  "queues": {
    "producers": [
      {
        "binding": "QUEUE",
        "queue": "MY_QUEUE_NAME",
      }
    ],
    "consumers": [
      {
        "queue": "MY_QUEUE_NAME",
        "max_batch_size": 10,
        "max_batch_timeout": 5
      }
    ]
  }
}

This will bind the queue to the env.QUEUE object in the worker. So you’ll be able to send messages.

Sending messages

src/worker.tsx

export default defineApp([
  route('/pay-with-ai', ({ env }) => {
    // Post a message to the queue
    env.QUEUE.send({
      userId: 1,
      amount: 100,
      currency: 'USD',
    })

    return new Response('Done!')
  })
])

Receiving messages

In order to “consume messages” from the queue you need to change the shape of the default export of your worker. You’ll add another function called queue that will receive a batch of messages.

src/worker.tsx

const app = defineApp([ /* routes... */])

export default {
  fetch: app.fetch,
  async queue(batch) {
    for (const message of batch) {
      console.log('handling message' + JSON.stringify(message))
    }
  }
} satisfies ExportedHandler<Env>;

This will receive a batch of messages, and process them one by one.