bullmq-job-architect

Designs production-grade BullMQ job queues with Redis, workers, DLQs, and monitoring.

1|Updated May 4, 2026
One-click install
npx skills add https://github.com/Scardubu/SwarmXQ --skill bullmq-job-architect-scardubu
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bullmq-job-architect
Source: https://github.com/Scardubu/SwarmXQ/tree/main/.ai/skills/bullmq-job-architect
Command: npx skills add https://github.com/Scardubu/SwarmXQ --skill bullmq-job-architect-scardubu

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires bullmq, ioredis, @bull-board/api, @bull-board/fastify.

What problem does it solve? Setting up background job processing with BullMQ involves non-obvious production pitfalls: shared Redis connections cause deadlocks, default worker concurrency of 1 bottlenecks throughput, and failed jobs vanish without a dead letter queue. This Skill provides a complete, correct-by-default architecture for BullMQ-based background job systems. ## Core Features & Use Cases - Queue Architecture: Enforces one queue per job type with separate ioredis connections for Queue, Worker, and QueueEvents roles, plus a concurrency sizing formula based on rate limits and job duration. - Failure Handling: Implements exponential backoff retries, dead letter queues with replay support, and graceful worker shutdown that drains active jobs before closing. - Advanced Patterns: Covers dependent job flows with FlowProducer, cron-based recurring jobs with stable jobIds, rate limiting for external API quotas, and Bull Board monitoring UI behind authentication. - Use Case: You need to send transactional emails, generate PDFs, and call LLM APIs in the background without one slow job type blocking the others. This Skill produces isolated queues with correctly sized workers, a DLQ for failed jobs, and a monitoring dashboard. ## Quick Start Ask the AI to set up a BullMQ background job architecture for your task, for example: "Set up BullMQ queues for email dispatch and PDF generation with a dead letter queue and Bull Board monitoring."

Frequently Asked Questions about bullmq-job-architect

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up a BullMQ job queue with Redis?

Create a Queue with its own ioredis connection, then a Worker with a separate connection to process jobs. Set maxRetriesPerRequest to null and enableReadyCheck to false in the Redis options, since BullMQ workers require these settings to avoid deadlocks.

How do I handle failed jobs in BullMQ?

Configure attempts with exponential backoff in defaultJobOptions, then listen for the worker failed event. When attemptsMade reaches the configured attempts, move the job to a dedicated dead letter queue that stores the original job data, error message, and stack for later replay.

How do I size BullMQ worker concurrency?

Use the formula concurrency equals ceil of rate limit per second times average job duration in seconds times a 1.2 buffer. For CPU-bound jobs like PDF generation, use os.cpus().length instead, and keep cron or scheduled jobs at concurrency 1.

Why does my BullMQ worker hang or deadlock?

Deadlocks typically occur when Queue, Worker, and QueueEvents share a single ioredis connection. BullMQ requires a separate connection instance per role, and the Redis config must set maxRetriesPerRequest to null and enableReadyCheck to false.

How do I schedule recurring cron jobs with BullMQ?

Add a job with a repeat option containing a cron pattern, and always set a stable jobId so the recurring job is not registered multiple times. Remove it later with removeRepeatable using the same name and pattern.

Does BullMQ support dependent jobs that run in sequence?

Yes, use FlowProducer to define a tree of parent and child jobs across multiple queues. BullMQ processes the tree bottom-up, so child jobs like validation complete before parent jobs like sending an email execute.