BullMQ

BullMQ is the default queue provider: Redis-backed, zero extra infrastructure in dev, and observable via Bull Board out of the box.

​

Why

BullMQ gives you persistent, retriable background jobs backed by Redis — the same Redis instance already used for caching. It ships with a dev UI (Bull Board), supports DLQs, and slots into the pluggable tooling system so you can swap it for another provider by changing one config value.

​

Setup

1. In apps/backend/package.json, ensure "tooling-queue-bullmq": "workspace:*" is listed under dependencies and remove any other queue adapter package.
2. Run make deps-install.
3. In development.ts, production.ts, and test.ts, set tools.queue:
   queue: {
     client: MQType.BULLMQ,
     connection: { url: process.env.REDIS_URL },
     queues: [
       {
         name: QueueName.YOUR_QUEUE,
         maxRetries: 3,
         maxMessages: 100,
         retryDelay: 1000,
         errorRetryDelaySeconds: 60,
         dlq: { name: QueueName.YOUR_QUEUE_DLQ, maxMessages: 100 },
       },
     ],
   }
   
4. In compose.yml, add the memory Redis service and bullmq-admin if not already present, and point backend, consumer, and migrator at depends_on: memory:
   memory:
     image: redis:latest
     ports:
       - 6379:6379
     healthcheck:
       test: ["CMD", "redis-cli", "ping"]
       interval: 2s
       timeout: 5s
       retries: 10
   
   bullmq-admin:
     image: nauverse/bull-board:latest
     environment:
       - REDIS_URL=redis://memory:6379
       - BULL_VERSION=BULLMQ
     depends_on:
       - memory
     ports:
       - "3998:3000"
   
5. In .env.development, set REDIS_URL=redis://memory:6379.
6. Run make test module=tooling-queue-bullmq and make test module=backend.

​

Local observability

Bull Board runs at http://localhost:3998 — it shows queue depth, job state, retries, and DLQ contents in real time. It reads directly from Redis, so it only reflects traffic when BullMQ is the active provider.

​

Adding a new queue

See Queue overview for the full client-agnostic steps (registry, config, consumer handler).

​

Gotchas

• Bull Board only shows traffic for the active provider. If you switch providers, the UI goes dark — that’s expected.
• Never mix queue providers between the API and consumer services in the same deployment.
• The memory Redis service is shared between tools.cache and tools.queue. Pointing REDIS_URL at a different instance for one tool will break the other unless you split the config intentionally.
• Never paste a production REDIS_URL into .env.development — rotate credentials immediately if that happens.

​

What’s next?

• Queue overview — consumers, deferred send, scaling rules.
• Scheduler overview — recurring work (may use SQS for execution).
• SQS — full guide to adopting SQS as an alternative provider.
• Configuration — switching pluggable tool implementations.
• Tooling system — how loaders and workspace packages fit together.