cloudflare-queues

Cloudflare Queues

Status: Production Ready ✅ | Last Verified: 2025-12-27

Dependencies: cloudflare-worker-base (for Worker setup)

Contents: Quick Start • Critical Rules • Top Errors • Use Cases • When to Load References • Limits

---

Quick Start (10 Minutes)

1. Create Queue

bunx wrangler queues create my-queue
bunx wrangler queues list

2. Producer (Send Messages)

wrangler.jsonc:

{
  "name": "my-producer",
  "main": "src/index.ts",
  "queues": {
    "producers": [
      {
        "binding": "MY_QUEUE",
        "queue": "my-queue"
      }
    ]
  }
}

src/index.ts:

import { Hono } from 'hono';

type Bindings = {
  MY_QUEUE: Queue;
};

const app = new Hono<{ Bindings: Bindings }>();

app.post('/send', async (c) => {
  await c.env.MY_QUEUE.send({
    userId: '123',
    action: 'process-order',
    timestamp: Date.now(),
  });

  return c.json({ status: 'queued' });
});

export default app;

3. Consumer (Process Messages)

wrangler.jsonc:

{
  "name": "my-consumer",
  "main": "src/consumer.ts",
  "queues": {
    "consumers": [
      {
        "queue": "my-queue",
        "max_batch_size": 10,
        "max_retries": 3,
        "dead_letter_queue": "my-dlq"
      }
    ]
  }
}

src/consumer.ts:

import type { MessageBatch } from '@cloudflare/workers-types';

export default {
  async queue(batch: MessageBatch): Promise<void> {
    for (const message of batch.messages) {
      console.log('Processing:', message.body);
      // Your logic here
    }
    // Implicit ack: returning successfully acknowledges all messages
  },
};

Deploy:

bunx wrangler deploy

Load: references/setup-guide.md for complete 6-step setup with DLQ configuration

---

Critical Rules

Always Do ✅

1. Configure Dead Letter Queue for production queues
2. Use explicit ack() for non-idempotent operations (DB writes, API calls)
3. Validate message size before sending (<128 KB)
4. Use sendBatch() for multiple messages (more efficient)
5. Implement exponential backoff for retries
6. Set appropriate batch settings based on workload
7. Monitor queue backlog and consumer errors
8. Use ctx.waitUntil() for async cleanup in consumers
9. Handle errors gracefully - log, alert, retry
10. Let concurrency auto-scale (don't set max_concurrency unless needed)