NestJS Bull & BullMQ Integration

To use the NestJS integration for the original Bull library, install both the NestJS wrapper and the bull package via npm.

$ npm i --save @nestjs/bull bull

To use the NestJS integration for BullMQ, install both the NestJS wrapper and the bullmq package via npm.

$ npm i --save @nestjs/bullmq bullmq

The @nestjs/bull package provides the core integration for Bull (the original Bull library) within NestJS. It exports the main BullModule for configuration, along with decorators, types, enums, and interfaces required to manage queues and process jobs.

Key components available from this entry point include:

• BullModule: The primary module used to register queues and configure the connection to Redis.
• Decorators: Used to inject queue instances and define job processors.
• Types and Interfaces: For type-safe job data and queue configurations.
• Enums: For standardized status and configuration values.

The @nestjs/bullmq package provides the core integration for BullMQ within the NestJS ecosystem. It exports the main BullModule for configuration, the BullRegistrar for managing multiple queues, and various decorators and types to facilitate job processing and queue interaction.

Key components include:

• BullModule: The primary module used to register and configure BullMQ queues.
• BullRegistrar: A service used to programmatically interact with registered queues.
• Decorators: Used to define job processors and inject queue instances.
• Types and Interfaces: Provide type safety for jobs, queues, and configuration objects.

The @nestjs/bull package uses internal factory functions to generate NestJS providers for Bull queues. When configuring a module, you provide BullModuleOptions which are used to create two types of providers:

1. Queue Options Provider: Created via getQueueOptionsToken(name). This provider holds the merged configuration for a specific queue, combining global shared configuration (if a configKey is provided) with the specific options defined for that queue.
2. Queue Provider: Created via getQueueToken(name). This provider returns the actual Bull.Queue instance, which is instantiated using the options from the Queue Options Provider.

To ensure clean shutdowns, the generated Queue instance is automatically configured to call .close() when the NestJS application shuts down.

To run a local Redis instance for use with Bull or BullMQ, you can use the provided docker-compose.yml configuration. This setup uses the redis:alpine image and maps the host port 6380 to the container port 6379. When configuring your NestJS Bull/BullMQ modules, ensure you connect to localhost:6380 instead of the default 6379.

version: "3"
services:
  redis:
    image: redis:alpine
    ports:
      - 6380:6379

When using BullModule.registerQueue(), you can provide configuration via BullModuleOptions. This interface extends the base Bull.QueueOptions and adds NestJS-specific properties for managing the queue within the module context.

Key properties:

• name: The name of the queue (defaults to default).
• configKey: A shared configuration key used for internal management (defaults to default).
• processors: An array of BullQueueProcessor to define additional queue processors.
• url: A Redis client connection string (inherited from BullRootModuleOptions).

// Example of what BullModuleOptions looks like in practice
const options: BullModuleOptions = {
  name: 'my-queue',
  url: 'redis://127.0.0.1:6379',
  processors: [], // Array of BullQueueProcessor
};

When using asynchronous configuration for the Bull module, you can use the SharedBullAsyncConfiguration object. This supports several patterns for providing the configuration:

• useExisting: Use an existing provider that implements SharedBullConfigurationFactory.
• useClass: Use a class that implements SharedBullConfigurationFactory.
• useFactory: A factory function that returns Bull.QueueOptions or a Promise<Bull.QueueOptions>.

Additional properties available:

• inject: List of providers to inject into the useFactory function.
• extraOptions: BullModuleExtraOptions (e.g., manualRegistration).
• extraProviders: Additional providers to register in the module context.
• imports: Standard NestJS module imports.

The BullRootModuleOptions interface defines the configuration for the root Bull module. It extends the standard Bull.QueueOptions from the underlying bullmq library and adds an extraOptions field of type BullModuleExtraOptions.

// The shape of BullRootModuleOptions
interface BullRootModuleOptions extends Bull.QueueOptions {
  extraOptions?: {
    manualRegistration?: boolean;
  };
}

The BullModuleExtraOptions interface allows you to control the module's automatic behavior. The primary option is manualRegistration. When set to true, the module will not automatically register Bull queues, which is useful if you need to manage queue registration manually.

// Example usage of manualRegistration
{
  extraOptions: {
    manualRegistration: true
  }
}

The MissingBullSharedConfigurationError is thrown when a queue configuration references a shared configuration key that has not been defined.

This typically happens when you provide a configuration key in the options for a specific queue (e.g., via BullModule.registerQueue()), but that key is missing from the global shared configuration provided to the Bull module.

Error Message Format: Configuration "<configKey>" referenced from the "Queue(<queueName>)" options does not exist.

To fix this:

1. Identify the configKey and queueName from the error message.
2. Ensure that the configKey is correctly defined in your shared Bull configuration.
3. Verify that the queue name matches the one being initialized.