BullMQ for Node.js

Background jobs for Node.js

The original BullMQ library. Background jobs and message queues for Node.js and TypeScript, on Redis or PostgreSQL.

npm install bullmq

Bun: bun add bullmq Yarn: yarn add bullmq pnpm: pnpm add bullmq

Node.js 14.17+ or Bun · Redis 6.2+ (or Valkey/Dragonfly) or PostgreSQL 13+

Get Started Source on GitHub

Quick start

Your first queue and worker

myQueue.ts

import { Queue } from "bullmq";

const queue = new Queue("Paint");
await queue.add("cars", { 
  color: "blue", 
  delay: 30000
});

myWorker.ts

import { Worker } from 'bullmq';

const worker = new Worker('Paint', async job => {
  if (job.name === 'cars') {
    await paintCar(job.data.color);
  }
}, { concurrency: 100 });

Shared core

The same job handling as the Node.js library

All BullMQ libraries run the same Lua scripts on Redis and the same SQL on PostgreSQL, so jobs are handled the same way in every language. Only the API around those scripts differs from one library to the next.

Examples

More Node.js examples

Common BullMQ features, written in Node.js.

Global events

events.ts

import { QueueEvents } from "bullmq";

const queueEvents = new QueueEvents("Paint");

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

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

Repeatable jobs

repeatable.ts

import { Queue } from 'bullmq';

const queue = new Queue('Paint');

// Repeat job once every day at 3:15 (am)
await queue.add(
  'submarine',
  { color: 'yellow' },
  {
    repeat: {
      pattern: '* 15 3 * * *',
    },
  },
);

Rate limiting

ratelimit.ts

import { Worker } from 'bullmq';

const worker = new Worker(
  'Paint',
  async job => paintCar(job),
  {
    limiter: {
      max: 10,
      duration: 1000,
    },
  }
);

Retries & backoff

retry.ts

import { Queue } from 'bullmq';

const queue = new Queue('Paint');

await queue.add(
  'car',
  { color: 'pink' },
  {
    attempts: 3,
    backoff: {
      type: 'exponential',
      delay: 1000,
    },
  },
);

Flows

flow.ts

import { FlowProducer } from "bullmq";

const flow = new FlowProducer();

await flow.add({
  name: "Renovate",
  queueName: "cars",
  children: [
    { name: "paint", queueName: "steps" },
    { name: "engine", queueName: "steps" },
    { name: "wheels", queueName: "steps" },
  ],
});

Ecosystem

Using BullMQ with Node.js

Node.js and Bun

The same package works on both runtimes, with no code changes.

Written in TypeScript

The API is fully typed, including generics for job data and return values.

Any framework

Use it from NestJS, Express, Fastify or Next.js, or run workers as a separate process.

Node.js Python, Rust, Elixir or .NET

Interoperability

One queue, any language

Add jobs from your Node.js API and process them with workers written in Python, Rust, Elixir or .NET. All of them read from the same queue.

Feature support

What's available in Node.js

Add jobs to queues Supported
Process jobs (workers) Supported
Delayed jobs Supported
Repeatable / scheduled jobs Supported
Job priorities Supported
Rate limiting Supported
Retries & backoff Supported
Flows (parent / child) Supported
Job events Supported
Redis backend Supported
PostgreSQL backend Supported
BullMQ Pro Supported

Pro

BullMQ Pro for Node.js Available now

BullMQ Pro is compatible with the open source package and adds groups, observables and batches, along with professional support from the BullMQ team.

Groups

Observables

Batches

Learn about BullMQ Pro

Runtimes

BullMQ in other languages

Python Rust Elixir PHP .NET Compare all

Get started with BullMQ for Node.js

Read the docs Star on GitHub