Bull Job Queue

A scalable and developer-ready background job queue system built on Bull and Redis. Supports retries, delays, dashboards, and REST control.

bullredisqueuejobsexpressbackgroundscheduler

v2.0.0utility

Overview

A robust, fault-tolerant job queue component for Express applications powered by Bull and Redis. Enables background processing, scheduled tasks, automatic retries, and includes a real-time web dashboard (Bull Board) for monitoring. Perfect for sending emails, processing uploads, caching, notifications, and other async workloads.

Installation

CLI

npx backternity add job-queue-bull

What This Does

Installs a complete Bull + Redis job queue system with REST endpoints, retry logic, and a Bull Board admin dashboard.

Files & Folders Created

File / Path	Description
/src/config/queue.js	Configures Bull and Redis connection.
/src/routes/jobs.js	REST API routes for job management.
/src/services/jobService.js	Add, fetch, and retry jobs.
/src/config/dashboard.js	Bull Board web UI setup.
/.env.example	Redis connection and queue settings.

Files to be modified

File / Path	Description
server.js	Mounts /api/jobs and /admin/queues routes.
.env	Adds Redis and queue configuration.

Configuration

# Redis Configuration
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# Queue Settings
QUEUE_NAME=background-jobs
MAX_RETRIES=3
PORT=3001

Frontend Integration

Use this component with your frontend (Next.js or React) to enqueue background jobs like sending emails, generating reports, or processing uploads. You can also monitor job progress using the built-in Bull Board UI.

POST/api/jobs/add

Adds a new job to the queue with optional delay or retries.

GET/api/jobs/status/job_64f8a4b2c1234567890abcde

Retrieves the status and result of a specific job.

POST/api/jobs/retry-failed

Retries all failed jobs currently in the queue.

GET/api/jobs/stats

Get queue statistics and job counts.

Example

// app/jobs/EnqueueJob.jsx (Next.js example)
'use client';
import { useState } from 'react';

export default function EnqueueJob() {
  const [jobId, setJobId] = useState(null);
  const [status, setStatus] = useState('');

  async function enqueueEmailJob() {
    setStatus('Submitting job...');
    try {
      const res = await fetch('/api/jobs/add', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ task: 'sendEmail', email: 'user@example.com' }),
      });
      const data = await res.json();
      if (data.success) {
        setJobId(data.jobId);
        setStatus('✅ Job queued successfully!');
      } else {
        setStatus('⚠️ Failed to queue job');
      }
    } catch (err) {
      setStatus('❌ Error connecting to job queue');
    }
  }

  async function checkStatus() {
    if (!jobId) return;
    const res = await fetch('/api/jobs/status/' + jobId);
    const data = await res.json();
    alert(JSON.stringify(data.status, null, 2));
  }

  return (
    <div className="p-4 border border-white/10 rounded-lg bg-black/30">
      <button
        onClick={enqueueEmailJob}
        className="bg-blue-600 hover:bg-blue-700 text-white px-4 py-2 rounded font-medium"
      >
        Queue Email Job
      </button>

      {jobId && (
        <button
          onClick={checkStatus}
          className="ml-3 bg-emerald-600 hover:bg-emerald-700 text-white px-4 py-2 rounded font-medium"
        >
          Check Job Status
        </button>
      )}

      <p className="text-sm text-gray-400 mt-3">{status}</p>
      <p className="text-xs text-gray-500 mt-1">
        🔍 Monitor queue: <a href="/admin/queues" className="underline">Bull Board Dashboard</a>
      </p>
    </div>
  );
}

Usage

// Enqueue and monitor background jobs
const { addJob, getJobStatus } = require('./src/services/jobService');

// Add new job
const job = await addJob({ task: 'emailReport', to: 'user@example.com' });

// Check status
const status = await getJobStatus(job.id);
console.log(status);