Cron jobs and schedulers with BullMQ

In-process cron (node-cron, @nestjs/schedule, OS crontab) runs inside one Node process. That is fine for a single instance, but it does not survive restarts gracefully, deduplicate across replicas, or share infrastructure with your other background jobs.

BullMQ stores queues and schedulers in Redis. Job Schedulers (BullMQ 5.16+) are the recommended way to enqueue recurring work on a cron pattern or fixed interval. The same workers that process one-off jobs also process scheduled ones, with retries, backoff, and concurrency you already get from BullMQ.

This post covers Job Schedulers in plain Node.js, operations and pitfalls, a NestJS setup with @nestjs/bullmq, and a runnable demo with a fast cron heartbeat and a daily cleanup cron.

Prerequisites

• Node.js version 26
• Redis at redis://localhost:6379 (included in the demo docker-compose.yml, or use Postgres and Redis containers with Docker Compose)
• npm i bullmq

For the NestJS section: npm i @nestjs/bullmq bullmq

BullMQ 2.0+ does not require a separate QueueScheduler instance. Use the Job Scheduler API (upsertJobScheduler), not the deprecated repeat option on queue.add().

Mental model

Piece	Role
Queue	Holds jobs waiting to run
Worker	Executes jobs
Job Scheduler	Factory that enqueues jobs on a schedule
Scheduled job	A job instance produced by a scheduler

A scheduler id is stable across deploys. Calling upsertJobScheduler with the same id updates the schedule in place instead of creating duplicates.

Queue and worker

Share one Redis connection config between the queue and the worker:

import { Queue, Worker } from 'bullmq';

const connection = { host: 'localhost', port: 6379 };

const queue = new Queue('reports', { connection });

const worker = new Worker(
  'reports',
  async (job) => {
    console.log(`[${job.name}]`, new Date().toISOString(), job.data);
  },
  { connection },
);

worker.on('failed', (job, error) => {
  console.error(job?.name, error.message);
});

Start the worker before or shortly after registering schedulers. If no worker is running, jobs accumulate in Redis until one picks them up.

Cron schedulers

BullMQ uses a 6-field cron expression (optional seconds). A fast pattern for demos and heartbeats:

await queue.upsertJobScheduler(
  'report-heartbeat',
  { pattern: '*/10 * * * * *' },
  {
    name: 'heartbeat',
    data: { source: 'scheduler' },
    opts: {
      attempts: 3,
      backoff: { type: 'exponential', delay: 1000 },
      removeOnComplete: 50,
    },
  },
);

Daily cleanup at 03:15 in a specific timezone:

await queue.upsertJobScheduler(
  'daily-cleanup',
  { pattern: '0 15 3 * * *', tz: 'Europe/Berlin' },
  {
    name: 'cleanup',
    data: { scope: 'stale-sessions' },
    opts: { attempts: 3 },
  },
);

Set tz when the job must fire at a local wall-clock time. For millisecond intervals instead of cron, use every (mutually exclusive with pattern).

Other useful repeat options:

Option	Purpose
limit	Maximum number of iterations
immediately	Run once now, then follow the schedule
startDate / endDate	Bound the scheduler to a time window

Register schedulers on startup

Keep scheduler registration in a dedicated bootstrap script or onModuleInit hook so deploys upsert the same ids:

// scheduler.js
import { Queue } from 'bullmq';

const connection = { host: 'localhost', port: 6379 };
const queue = new Queue('reports', { connection });

await queue.upsertJobScheduler(
  'report-heartbeat',
  { pattern: '*/10 * * * * *' },
  { name: 'heartbeat', data: { source: 'scheduler' } },
);

await queue.upsertJobScheduler(
  'daily-cleanup',
  { pattern: '0 15 3 * * *', tz: 'Europe/Berlin' },
  { name: 'cleanup', data: { scope: 'stale-sessions' } },
);

const schedulers = await queue.getJobSchedulers();
console.log(
  'Active schedulers:',
  schedulers.map((item) => ({ key: item.key, pattern: item.pattern })),
);

await queue.close();

To remove a scheduler:

await queue.removeJobScheduler('daily-cleanup');

Shut down cleanly on SIGINT / SIGTERM: await worker.close() and await queue.close().

NestJS with @nestjs/bullmq

NestJS wraps BullMQ queues and workers as providers. Register Redis once, register the queue, inject it into a service that upserts schedulers on startup, and process jobs in a @Processor class.

// app.module.ts
import { Module } from '@nestjs/common';
import { BullModule } from '@nestjs/bullmq';
import { ReportsProcessor } from './reports.processor';
import { ReportsSchedulerService } from './reports-scheduler.service';

@Module({
  imports: [
    BullModule.forRoot({
      connection: { host: 'localhost', port: 6379 },
    }),
    BullModule.registerQueue({ name: 'reports' }),
  ],
  providers: [ReportsProcessor, ReportsSchedulerService],
})
export class AppModule {}

// reports-scheduler.service.ts
import { Injectable, OnModuleInit } from '@nestjs/common';
import { InjectQueue } from '@nestjs/bullmq';
import { Queue } from 'bullmq';

@Injectable()
export class ReportsSchedulerService implements OnModuleInit {
  constructor(@InjectQueue('reports') private readonly reportsQueue: Queue) {}

  async onModuleInit() {
    await this.reportsQueue.upsertJobScheduler(
      'report-heartbeat',
      { pattern: '*/10 * * * * *' },
      { name: 'heartbeat', data: { source: 'nestjs' } },
    );

    await this.reportsQueue.upsertJobScheduler(
      'daily-cleanup',
      { pattern: '0 15 3 * * *', tz: 'Europe/Berlin' },
      { name: 'cleanup', data: { scope: 'stale-sessions' } },
    );
  }
}

// reports.processor.ts
import { Processor, WorkerHost } from '@nestjs/bullmq';
import { Job } from 'bullmq';

@Processor('reports')
export class ReportsProcessor extends WorkerHost {
  async process(job: Job): Promise<void> {
    console.log(`[${job.name}]`, new Date().toISOString(), job.data);
  }
}

ReportsSchedulerService runs when the Nest app boots, so schedulers are upserted on every deploy. ReportsProcessor is the worker; Nest registers it automatically unless you set manualRegistration on BullModule.forRoot.

@nestjs/schedule (@Cron()) is still a good fit for trivial timers inside one instance. Prefer BullMQ schedulers when you already use Redis queues, run multiple replicas, or need the same retry and observability model as the rest of your background jobs.

Pitfalls

• Worker must be running - schedulers enqueue jobs; something must consume them.
• Busy queues slip - BullMQ creates the next scheduled job when the previous one starts processing. Under load, ticks can be less frequent than every or the cron interval suggests.
• pattern vs every - mutually exclusive; pick one per scheduler.
• Timezone - omit tz and cron runs in the server default zone; set it explicitly for "9 AM local" jobs.
• Legacy repeat on add() - deprecated from BullMQ 5.16; use upsertJobScheduler for new code.

When to use what

Approach	Good for
@nestjs/schedule / node-cron	Single instance, simple in-process timers
BullMQ Job Schedulers	Multi-instance apps, shared Redis, retries with async jobs
External cron + HTTP	Fire-and-forget HTTP triggers without queue semantics

Need help with your project?

Get personalized advice on your architecture, code, or career in a 45-minute 1-on-1 consultation.

→ Book a consultation