{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "dist",
    "baseUrl": ".",
    "paths": {
      "bullmq": ["./src/bullmq-source/index.ts"]
    }
  },
  "include": ["src/**/*"]
}

3. Set environment variables your application uses to configure the Redis connection:

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=

4. Import from the barrel entry point:

import { Queue, Worker, Job, FlowProducer, QueueEvents } from 'bullmq';

5. If you are loading from the raw source path instead of the npm package, replace the import path with './bullmq-source' or the alias you configured in tsconfig.json.

Public API

Queue

class Queue<DataType = any, ReturnType = any, NameType extends string = string>
  extends QueueGetters<DataType, ReturnType, NameType> {
  constructor(name: string, opts?: QueueOptions);
  add(name: NameType, data: DataType, opts?: JobsOptions): Promise<Job<DataType, ReturnType, NameType>>;
  addBulk(jobs: { name: NameType; data: DataType; opts?: BulkJobOptions }[]): Promise<Job[]>;
  getJob(jobId: string): Promise<Job | undefined>;
  pause(): Promise<void>;
  resume(): Promise<void>;
  close(): Promise<void>;
}

Use Queue to enqueue jobs from any producer process. Pass QueueOptions with a connection field pointing to your ioredis options. Call add to push a single job and addBulk for batches.

Worker

class Worker<DataType = any, ReturnType = any, NameType extends string = string>
  extends MainWorker<DataType, ReturnType, NameType> {
  constructor(
    name: string,
    processor: Processor<DataType, ReturnType, NameType> | string | null,
    opts?: WorkerOptions,
  );
  on(event: 'completed', listener: (job: Job, result: ReturnType) => void): this;
  on(event: 'failed', listener: (job: Job | undefined, error: Error) => void): this;
  close(force?: boolean): Promise<void>;
}

Use Worker to consume jobs. The second argument is either an async function (inline processor) or a path string to a sandboxed child-process module. Attach completed and failed listeners for observability.

FlowProducer

class FlowProducer extends MainBase {
  constructor(opts?: QueueBaseOptions);
  add(flow: FlowJob, opts?: FlowOpts): Promise<JobNode>;
  addBulk(flows: FlowJob[], opts?: FlowOpts): Promise<JobNode[]>;
  close(): Promise<void>;
}

Use FlowProducer when jobs have parent-child dependencies. A parent job waits in the waiting-children state until all its children complete. Nest FlowJob objects to declare the dependency tree declaratively.

QueueEvents

class QueueEvents extends QueueBase {
  constructor(name: string, opts?: QueueEventsOptions);
  on(event: 'completed', listener: (args: { jobId: string; returnvalue: string }) => void): this;
  on(event: 'failed', listener: (args: { jobId: string; failedReason: string }) => void): this;
  on(event: 'progress', listener: (args: { jobId: string; data: number | object }) => void): this;
  close(): Promise<void>;
}

Use QueueEvents in monitoring services or API servers to receive real-time job lifecycle events over a dedicated Redis connection without polling.

Working examples

Scenario - Basic producer / worker pair

A minimal setup that enqueues an email job and processes it in a worker.

import { Queue, Worker, Job } from 'bullmq';
import IORedis from 'ioredis';

const connection = new IORedis({
  host: process.env.REDIS_HOST ?? '127.0.0.1',
  port: Number(process.env.REDIS_PORT ?? 6379),
  maxRetriesPerRequest: null,
});

const emailQueue = new Queue('email', { connection });

// Producer: add a job
await emailQueue.add('send-welcome', { to: 'user@example.com', template: 'welcome' });

// Worker: process jobs
const worker = new Worker<{ to: string; template: string }>(
  'email',
  async (job: Job) => {
    console.log(`Sending ${job.data.template} email to ${job.data.to}`);
    // call your mailer here
  },
  { connection },
);

worker.on('completed', (job) => console.log(`Job ${job.id} completed`));
worker.on('failed', (job, err) => console.error(`Job ${job?.id} failed:`, err.message));

Scenario - Flow with parent-child dependencies

Processes video: extract audio and generate thumbnail in parallel, then package only after both finish.

import { FlowProducer, FlowJob } from 'bullmq';
import IORedis from 'ioredis';

const connection = new IORedis({ host: '127.0.0.1', port: 6379, maxRetriesPerRequest: null });
const flow = new FlowProducer({ connection });

const tree = await flow.add({
  name: 'package-video',
  queueName: 'video-pipeline',
  data: { videoId: 'abc123' },
  children: [
    { name: 'extract-audio', queueName: 'video-pipeline', data: { videoId: 'abc123' } },
    { name: 'gen-thumbnail', queueName: 'video-pipeline', data: { videoId: 'abc123' } },
  ],
} as FlowJob);

console.log('Root job id:', tree.job.id);
await flow.close();

Scenario - Repeatable scheduled job via JobScheduler

Schedules a report job to run every hour using a cron expression.

import { Queue } from 'bullmq';
import IORedis from 'ioredis';

const connection = new IORedis({ host: '127.0.0.1', port: 6379, maxRetriesPerRequest: null });
const reportQueue = new Queue('reports', { connection });

await reportQueue.upsertJobScheduler(
  'hourly-report',
  { pattern: '0 * * * *' },
  {
    name: 'generate-report',
    data: { type: 'sales' },
    opts: { attempts: 3, backoff: { type: 'exponential', delay: 5000 } },
  },
);

console.log('Scheduler registered');
await reportQueue.close();

Scenario - Monitoring with QueueEvents

Listens for completed and failed events without running a worker.

import { QueueEvents } from 'bullmq';
import IORedis from 'ioredis';

const connection = new IORedis({ host: '127.0.0.1', port: 6379, maxRetriesPerRequest: null });
const events = new QueueEvents('email', { connection });

events.on('completed', ({ jobId, returnvalue }) => {
  console.log(`Job ${jobId} done, result:`, returnvalue);
});

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

File walkthrough

• index.ts - Barrel re-export for the entire library; import everything from here.
• version.ts - Exports the current package version string.
• classes/queue.ts - Queue class: add, remove, pause, drain, and inspect jobs.
• classes/worker.ts - Worker class: polling loop, concurrency control, rate limiting, sandboxed processors.
• classes/job.ts - Job class: represents a single job instance with state transitions, progress updates, and retry logic.
• classes/job-scheduler.ts - JobScheduler: manages repeatable/cron job records in Redis.
• classes/flow-producer.ts - FlowProducer: creates parent-child job trees atomically.
• classes/queue-events.ts - QueueEvents: subscribes to Redis streams for real-time job events.
• classes/queue-getters.ts - QueueGetters: read-side helpers (counts, job lists, metrics).
• classes/redis-connection.ts - RedisConnection: manages ioredis lifecycle, reconnection, and script loading.
• classes/scripts.ts - Scripts: wrappers around all Lua command calls.
• classes/backoffs.ts - Built-in backoff strategies (fixed, exponential, custom).
• classes/child-pool.ts / classes/child-processor.ts - Sandboxed worker subprocess management.
• classes/errors/ - Typed error classes for specific failure modes.
• commands/ - ScriptLoader that reads .lua files and loads them into Redis as commands.
• enums/ - Shared numeric/string enums for commands, error codes, and metrics.
• interfaces/ - All TypeScript option and data interfaces (e.g. QueueOptions, WorkerOptions, JobsOptions).
• types/ - Type aliases including Processor<DataType, ReturnType>.
• utils/ - Low-level helpers re-exported for advanced users.

Common pitfalls and fixes

• maxRetriesPerRequest not set to null: ioredis will throw on blocking commands; always pass maxRetriesPerRequest: null in the connection options used by Worker.
• Redis version below 6.2: BullMQ uses streams and Lua scripts that require Redis 6.2+; upgrade Redis or use a Dragonfly-compatible instance.
• Worker closes before jobs finish: call await worker.close() (not process.exit()) to drain in-flight jobs gracefully; use close(true) only for forced shutdown.
• Duplicate script loading on hot reload: reuse a single RedisConnection instance or the singleton scriptLoader from commands/; instantiating multiple connections per process wastes memory and causes script re-upload on every reload.
• ESM/CJS interop with import IORedis: use import IORedis from 'ioredis' (default import) with "esModuleInterop": true in tsconfig.json; named imports will fail.
• Sandboxed processor path must be an absolute path: when passing a file path string to Worker, resolve it with path.resolve(__dirname, './processor.js') or the worker will silently fail to spawn.

Vibe-coding prompt template

I have the BullMQ source (bullmq@5.75.0) available at `source/` and the
integration guide at `USAGE.md`. Using only the real exports documented in
USAGE.md and visible in source/index.ts, source/classes/index.ts, and the
related interface/type files, please help me integrate BullMQ into my
existing Node.js/TypeScript project step by step.

My project uses:
- Node.js (version: ?)
- TypeScript (version: ?)
- Express / Fastify / NestJS (pick one)
- Redis at <host>:<port>

Tasks I need:
1. Set up a Queue named "<queue-name>" with my Redis connection.
2. Add a Worker that processes jobs of type <describe job shape>.
3. Add error handling using the typed errors from source/classes/errors/.
4. (Optional) Set up a repeatable job using Queue.upsertJobScheduler.
5. (Optional) Set up a FlowProducer for parent-child job dependencies.

Please show complete, runnable TypeScript code, import only from 'bullmq'
(mapping to source/), and follow the patterns in USAGE.md.

License and credit

BullMQ is released under the MIT License. See the source/ directory for LICENSE if present, or refer to the upstream repository. Upstream package: bullmq on npm maintained by Taskforce.sh. Source repository: taskforcesh/bullmq on GitHub.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Graphile Worker PostgreSQL Background Job Queue

SaaS, AI & Subscription Products

Free