home / skills / hoangnguyen0403 / agent-skills-standard / nestjs-bullmq

nestjs-bullmq skill

This skill helps you implement robust, type-safe background jobs in NestJS using BullMQ with producer-consumer pattern.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill nestjs-bullmq

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.7 KB

---
name: NestJS BullMQ Implementation
description: Standard workflow for implementing background jobs using BullMQ in NestJS.
metadata:
  labels: [nestjs, bullmq, background-jobs, queue, redis]
  triggers:
    files: ['package.json', '**/*.module.ts']
    keywords: [queue, backlog, background job, async task, worker]
---

# NestJS BullMQ Implementation

## **Priority: P0 (Standard)**

Implement type-safe, robust background jobs using the `Producer-Consumer` pattern with `@nestjs/bullmq`.

## Structure

```text
src/modules/{feature}/
├── {feature}-queue.service.ts  # Producer: Schedules jobs
├── {feature}.processor.ts      # Consumer: Processes jobs
└── {feature}.module.ts         # Config: Registers queues
```

## Implementation Guidelines

- **Use Producers**: create a dedicated `QueueService` to wrap `queue.add()`.
- **Use Consumers**: extend `WorkerHost` and decorate with `@Processor(QUEUE_NAME)`.
- **Enforce Types**: Define interfaces for `JobData` to ensure payload safety.
- **Manage Lifecycle**: Set `removeOnComplete: true` to prevent Redis memory bloat.
- **Handle Errors**: Use `removeOnFail` limit or Dead Letter Queues (DLQ) for debugging.
- **Unique IDs**: Provide deterministic `jobId` if you need to cancel/deduplicate jobs later.

## Anti-Patterns

- **No Strings**: Define queue names as constants, not inline strings.
- **No Heavy Logic**: Do not put complex business logic in `QueueService`; only schedule.
- **Avoid Implicit cleanup**: Always configure job cleanup policies explicitly.
- **No Direct Redis**: Use `InjectQueue` annotations, avoided raw Redis commands.

## Reference & Examples

For complete code patterns: [references/patterns.md](references/patterns.md)

Overview

This skill describes a standard, type-safe approach for implementing background jobs in NestJS using BullMQ. It defines a clear Producer-Consumer pattern, module layout, and operational rules to keep job processing robust and maintainable. The guidance focuses on lifecycle, error handling, and avoiding common anti-patterns.

How this skill works

Create a QueueService per feature to act as the producer and push typed job payloads with queue.add(). Implement consumers by extending WorkerHost and decorating with @Processor(QUEUE_NAME) to process jobs. Register queues in the feature module and use lifecycle options like removeOnComplete and removeOnFail or a Dead Letter Queue to manage Redis state and failures.

When to use it

Offload long-running tasks (file processing, image transforms, exports) from HTTP request paths.
Schedule retries, delayed tasks, or periodic jobs that must persist across restarts.
Coordinate background workflows where job deduplication or cancellation is required.
Process events at scale with predictable concurrency and backpressure control.
Implement DLQs or controlled failure handling for critical background operations.

Best practices

Structure each feature with {feature}-queue.service.ts, {feature}.processor.ts, and {feature}.module.ts for clear separation.
Define interfaces for JobData and use TypeScript types to enforce payload contracts.
Keep QueueService lightweight: only schedule jobs; put business logic in processors or application services.
Declare queue names as constants and use InjectQueue; avoid inline string names and raw Redis commands.
Set removeOnComplete and configure removeOnFail or DLQs to prevent Redis bloat and aid debugging.
Provide deterministic jobId when you need to deduplicate or cancel jobs later.

Example use cases

Uploading large files: accept upload, immediately schedule a processing job that resizes and stores derivatives.
Email campaigns: enqueue templated emails with deterministic jobId to avoid duplicate sends.
Data exports: create a job that generates reports, stores results, and notifies users when ready.
Thumbnail generation: producer receives upload event; consumer creates thumbnails asynchronously.
Retryable API calls: schedule background retries with backoff and move failing jobs to a DLQ for inspection.

FAQ

How should I choose between removeOnFail and a Dead Letter Queue?

Use removeOnFail for short-term failures you don’t need to inspect; use a DLQ when you need to preserve failed payloads for debugging, replay, or manual handling.

Where should complex business logic live?

Keep complex logic out of the QueueService. Implement business rules in processors or dedicated application services invoked by the processor to keep producers simple and testable.