{
  "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.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Graphile Worker PostgreSQL Background Job Queue

SaaS, AI & Subscription Products

무료