⏰ Scheduled Tasks with Cron

Why Schedule Work?

Think of the automatic systems around your home: the thermostat that lowers the heat at night, the coffee maker that starts at 6 AM, the phone that backs itself up while you sleep. None of them wait for you to press a button. A web application has the same kind of recurring housekeeping, and a scheduler is what runs it on time, every time, without a human.

Scheduled tasks are just background jobs with a trigger that is time rather than a user action. Everything you learned about workers, retries, and idempotency still applies — we're only adding "run this on a schedule" to the front of it.

Reading Cron Expressions

Cron is a time-based scheduler born on Unix (the name comes from chronos, Greek for time). Its expressions are a compact language for "when should this run," and the same syntax is used by node-cron, BullMQ, GitHub Actions, and cloud schedulers. Learn it once, use it everywhere.

A standard cron expression has five fields separated by spaces:

┌───────────── minute        (0 - 59)
│ ┌─────────── hour          (0 - 23)
│ │ ┌───────── day of month  (1 - 31)
│ │ │ ┌─────── month         (1 - 12)
│ │ │ │ ┌───── day of week   (0 - 6, Sunday = 0)
│ │ │ │ │
* * * * *

The special characters

• * — every value (a wildcard). * * * * * means "every minute."
• , — a list. 0 9,17 * * * is 9 AM and 5 PM.
• - — a range. 0 9 * * 1-5 is 9 AM Monday through Friday.
• / — a step. */15 * * * * is every 15 minutes.

Expressions you'll actually use

Scheduling with node-cron

node-cron is a tiny, zero-dependency scheduler that runs cron jobs inside your Node process. It's the fastest way to add a recurring task and perfect for lightweight, single-instance jobs.

// npm install node-cron
import cron from 'node-cron';

// Every day at 3:00 AM: clean up expired sessions.
cron.schedule('0 3 * * *', async () => {
  console.log('Running nightly session cleanup…');
  await Session.deleteExpired();
});

// Every 15 minutes: check inventory and alert on low stock.
cron.schedule('*/15 * * * *', async () => {
  await checkLowStock();
});

node-cron validates expressions, so a typo throws immediately rather than silently never running. You can also pin a task to a specific time zone — essential when "midnight" needs to mean midnight for your users, not for the server.

cron.schedule('0 0 * * *', () => {
  console.log('Midnight in New York, regardless of server location');
}, {
  timezone: 'America/New_York'
});

Separate the task from the schedule

Don't bury business logic inside the cron callback — you can't unit-test a schedule. Keep the what (the task) apart from the when (the schedule).

// tasks.js — the "what", pure and testable
export async function cleanupSessions() {
  const removed = await Session.deleteExpired();
  console.log(`Removed ${removed} expired sessions`);
}

// scheduler.js — the "when"
import cron from 'node-cron';
import { cleanupSessions } from './tasks.js';

cron.schedule('0 3 * * *', cleanupSessions);

BullMQ Repeatable Jobs

BullMQ can schedule too — and because the schedule lives in Redis, it survives restarts and is shared across every worker. You define a repeatable job with a cron pattern; BullMQ enqueues a fresh job each time the pattern fires, and your existing worker processes it with all the retries and backoff you already built.

// producer side — register the repeatable job once at startup
import { Queue } from 'bullmq';
import { connection } from './queues/connection.js';

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

// Every day at 3 AM, enqueue a 'daily-summary' run.
await reportQueue.add(
  'daily-summary',
  { kind: 'daily' },
  {
    repeat: { pattern: '0 3 * * *', tz: 'America/New_York' },
    removeOnComplete: 100,
    removeOnFail: 500
  }
);

The worker is exactly the kind you built last lesson — it doesn't know or care that the job was scheduled rather than triggered by a user.

// worker.js — runs in its own process
import { Worker } from 'bullmq';
import { connection } from './queues/connection.js';

const worker = new Worker('reports', async (job) => {
  console.log(`Generating ${job.data.kind} report at ${new Date().toISOString()}`);
  await generateReport(job.data.kind);
  return { generatedAt: Date.now() };
}, { connection });

One-off delayed jobs

Not everything repeats. To run something once at a future time — say, a reminder 24 hours after signup — use a plain delay instead of repeat.

await reminderQueue.add(
  'day-1-reminder',
  { userId: 42 },
  { delay: 24 * 60 * 60 * 1000 }   // fire once, 24 hours from now
);

Managing repeatable jobs

Adding the same repeatable pattern twice does not create duplicates — BullMQ keys them by name + pattern. To change or stop a schedule, remove the old one.

// List what's scheduled
const schedulers = await reportQueue.getJobSchedulers();

// Remove a repeatable job by its scheduler id
await reportQueue.removeJobScheduler('daily-summary');

Idempotency, Locking & Time Zones

Scheduled tasks fail in three classic ways. Guard against all three and yours will run reliably for years.

1. Idempotency

A schedule can misfire, overlap, or be retried — so a task must be safe to run more than once for the same period. Stamp the work with the date and check before acting.

// ✅ Idempotent daily newsletter — skips anyone already sent today
async function sendDailyNewsletter() {
  const today = new Date().toISOString().slice(0, 10);   // "2026-07-31"

  const users = await User.findSubscribedWithoutSendOn('daily', today);
  for (const user of users) {
    await mailer.send(user.email, 'daily-newsletter');
    await SendLog.record({ userId: user.id, type: 'daily', date: today });
  }
}

2. Prevent overlapping runs

If a task occasionally takes longer than its interval, the next tick can start before the last finished — two copies clobbering each other. A short-lived Redis lock ensures only one runs at a time.

async function runWithLock(key, ttlSeconds, task) {
  // SET key value NX EX ttl — succeeds only if the key doesn't exist.
  const acquired = await redis.set(key, '1', 'NX', 'EX', ttlSeconds);
  if (!acquired) {
    console.log('Another run holds the lock — skipping this tick');
    return;
  }
  try {
    await task();
  } finally {
    await redis.del(key);   // release even if the task throws
  }
}

cron.schedule('*/5 * * * *', () => runWithLock('sync-lock', 300, syncData));

This same lock trick lets you run node-cron across several instances safely: all three fire, but only the one that grabs the lock actually works.

3. Time zones

Servers usually run in UTC, but "9 AM" means a wall-clock time to your user. Always specify a timezone/tz for user-facing schedules, and store timestamps in UTC. Don't assume the server's local zone.

cron.schedule('0 0 * * *', async () => {
  const start = Date.now();
  try {
    await performBackup();
    console.log(`Backup ok in ${Date.now() - start}ms`);
  } catch (err) {
    console.error('Backup FAILED:', err);
    await alerts.notify('Nightly backup failed', err);
  }
});

Practice & Quiz

1. 30 2 * * *      # 2:30 AM daily
2. */10 * * * *    # every 10 minutes
3. 0 9 * * 1       # 9:00 AM every Monday
4. 0 0 1 * *       # midnight on the 1st of each month

cron.schedule('0 8 * * *', () => sendMorningDigest(), {
  timezone: 'America/New_York'
});

import { Queue } from 'bullmq';
import { connection } from './queues/connection.js';

const digestQueue = new Queue('digest', { connection });

await digestQueue.add(
  'morning-digest',
  {},
  {
    repeat: { pattern: '0 8 * * *', tz: 'America/New_York' },
    removeOnComplete: 50,
    removeOnFail: 200
  }
);

// A single Worker (in its own process) runs sendMorningDigest(),
// and BullMQ enqueues exactly one run per day no matter how many
// API instances registered the repeatable job.

Best Practices & Pitfalls

✅ Do

• Keep the task separate from the schedule so you can test the logic
• Make every scheduled task idempotent — stamp work with a date and check first
• Specify a time zone for user-facing schedules; store timestamps in UTC
• Wrap task bodies in try/catch, then log, record metrics, and alert on failure
• Use a lock (or a queue) to prevent overlapping and multi-instance double-runs

❌ Don't

• Don't rely on in-process node-cron for critical jobs across multiple instances
• Don't let an unhandled rejection in a cron callback crash your server
• Don't assume the server's local time — be explicit about zones
• Don't schedule heavy work to all run at exactly midnight; stagger to avoid a thundering herd

Summary

📚 Additional Resources

• node-cron — Official documentation
• BullMQ — Repeatable jobs guide
• crontab.guru — Cron expression explainer
• Vercel Cron Jobs (serverless scheduling)

🚀 What's Next?

You've now completed Week 10's background-jobs arc: queues, workers, and schedules. Next you'll put the whole stack together in the weekend project — Build a Full-Stack Social Media Application — where background jobs power the feed fan-out, notifications, and image processing you just learned to run off the request path.