bullmq

BullMQ

Redis-backed queue system for Node.js. Four core classes: Queue, Worker, QueueEvents, FlowProducer.

Table of Contents

• Install
• Quick Start
• Connections
• Queue
• Worker
• TypeScript Generics
• Events
• Job Lifecycle States
• Advanced Topics

Install

yarn add bullmq — requires Redis 5.0+ with maxmemory-policy=noeviction.

<quick_reference>

Quick Start

import { Queue, Worker, QueueEvents } from "bullmq";

// --- Producer ---
const queue = new Queue("my-queue", {
  connection: { host: "localhost", port: 6379 },
});

await queue.add("job-name", { foo: "bar" });

// --- Consumer ---
const worker = new Worker(
  "my-queue",
  async (job) => {
    // process job
    await job.updateProgress(50);
    return { result: "done" };
  },
  { connection: { host: "localhost", port: 6379 } },
);

worker.on("completed", (job, returnvalue) => {
  console.log(`${job.id} completed with`, returnvalue);
});

worker.on("failed", (job, err) => {
  console.error(`${job.id} failed with`, err.message);
});

// IMPORTANT: always attach an error handler
worker.on("error", (err) => {
  console.error(err);
});

// --- Global event listener (all workers) ---
const queueEvents = new QueueEvents("my-queue", {
  connection: { host: "localhost", port: 6379 },
});

queueEvents.on("completed", ({ jobId, returnvalue }) => {
  console.log(`Job ${jobId} completed`);
});

queueEvents.on("failed", ({ jobId, failedReason }) => {
  console.error(`Job ${jobId} failed: ${failedReason}`);
});

Job Lifecycle States

add() → wait / prioritized / delayed
         ↓
       active → completed
         ↓
       failed → (retry) → wait/delayed

With FlowProducer: jobs can also be in waiting-children state until all children complete.

</quick_reference>

Connections

BullMQ uses ioredis internally. Pass connection options or an existing ioredis instance.