@studiosonrai/nestjs-queue-meta

Labels BullMQ queues with the owning application name in Redis. This enables the queue-dashboard to auto-discover and group queues by application without any static configuration.

How it works

On application startup, the module discovers all BullMQ Queue instances registered in the NestJS DI container and writes two fields to each queue's Redis meta hash:

HSET {prefix}:{queueName}:meta app {appName} prefix {prefix}

• app - the application name (used for grouping in the dashboard)
• prefix - the BullMQ key prefix (used by the dashboard to create Queue instances with the correct namespace)

This is idempotent - restarting the app re-writes the same values. Existing queue data (jobs, state, history) is not affected.

Installation

npm install @studiosonrai/nestjs-queue-meta

Peer dependencies: @nestjs/common, @nestjs/core, @nestjs/bullmq, bullmq

Usage

Import QueueMetadataModule in the same module where BullModule.forRootAsync is configured. Pass the application name as the argument:

import { BullModule } from '@nestjs/bullmq';
import { QueueMetadataModule } from '@studiosonrai/nestjs-queue-meta';

@Module({
  imports: [
    BullModule.forRootAsync({
      useFactory: (config: ConfigService) => ({
        connection: config.get('redis'),
        prefix: 'my-app', // optional, defaults to 'bull'
      }),
      inject: [ConfigService],
    }),
    QueueMetadataModule.forRoot('my-app'),
    BullModule.registerQueue(
      { name: 'emails' },
      { name: 'uploads' },
    ),
  ],
})
export class AppModule {}

That's it. All queues registered via BullModule.registerQueue will be labelled automatically. No need to list queue names again.

What gets written to Redis

Given the example above with prefix my-app:

my-app:emails:meta  -> { app: "my-app", prefix: "my-app", ...existing BullMQ fields }
my-app:uploads:meta -> { app: "my-app", prefix: "my-app", ...existing BullMQ fields }

With the default prefix (bull):

bull:emails:meta -> { app: "my-app", prefix: "bull", ...existing BullMQ fields }

API

QueueMetadataModule.forRoot(appName: string)

Returns a global dynamic module. Only needs to be imported once per application.

| Parameter | Type | Description | |---|---|---| | appName | string | Application name written to the app field in each queue's meta hash |