Node.js Cron Job Guide: node-cron, node-schedule, and cron

Why Node.js Needs a Cron Library

The OS-level crontabruns shell commands — it doesn't know about your Node.js app's dependencies, environment variables, database connections, or in-memory state. Running a separate Node process per cron job adds startup overhead and loses shared resources.

In-process Node.js cron libraries solve this by running scheduled tasks inside your running application:

• • No startup overhead — reuse DB connections, caches, service objects
• • Full access to app environment and configuration
• • Easier logging, error handling, and observability
• • Portable — works the same on Linux, macOS, Windows, Docker, and cloud

node-cron: The Most Popular Choice

node-cron (~5M weekly downloads) is the go-to choice for most Node.js projects. It uses a 5-field cron syntax (with optional seconds as a 6th field) and has a clean, minimal API.

Installation

npm install node-cron
# TypeScript — types are built-in

Basic Usage

import cron from 'node-cron';

// Run every minute
cron.schedule('* * * * *', () => {
  console.log('Running every minute');
});

// Run at 2:30 AM every day
cron.schedule('30 2 * * *', async () => {
  await sendDailyReport();
});

// Run at 9 AM Monday–Friday
cron.schedule('0 9 * * 1-5', async () => {
  await sendStandupReminder();
});

// Run every 5 minutes
cron.schedule('*/5 * * * *', () => {
  checkHealthEndpoints();
});

6-Field Syntax (with Seconds)

// Enable 6-field mode with { scheduled: true }
// Fields: second minute hour day month weekday
cron.schedule('*/30 * * * * *', () => {
  // Runs every 30 seconds
  pollExternalApi();
});

Timezone Support

// Schedule in a specific timezone
cron.schedule(
  '0 9 * * 1-5',   // 9 AM weekdays
  async () => {
    await sendMorningDigest();
  },
  {
    timezone: 'America/New_York',
  }
);

Start / Stop / Destroy

// Create but don't start immediately
const task = cron.schedule(
  '0 * * * *',
  () => { syncDatabase(); },
  { scheduled: false }   // won't run until started
);

task.start();   // begin executing
task.stop();    // pause (can restart)
task.destroy(); // remove from scheduler (cannot restart)

Validate Before Scheduling

import cron from 'node-cron';

const expression = process.env.SYNC_SCHEDULE ?? '0 */6 * * *';

if (!cron.validate(expression)) {
  throw new Error(`Invalid cron expression: ${expression}`);
}

cron.schedule(expression, syncUsers);

node-schedule: Cron + One-Time Jobs

node-schedule supports both cron-style recurring schedules and one-time future jobs. It exposes a RecurrenceRule API that is more explicit than cron strings, useful when you want to avoid memorizing syntax.

Installation

npm install node-schedule
npm install --save-dev @types/node-schedule  # TypeScript

Cron-String Scheduling

import schedule from 'node-schedule';

// Standard 5-field cron expression
const job = schedule.scheduleJob('0 3 * * *', async () => {
  await runNightlyBackup();
});

// Cancel when done
job.cancel();

RecurrenceRule API

import schedule, { RecurrenceRule } from 'node-schedule';

const rule = new RecurrenceRule();
rule.dayOfWeek = [1, 2, 3, 4, 5]; // Monday–Friday
rule.hour = 9;
rule.minute = 0;
rule.tz = 'America/Chicago';

const job = schedule.scheduleJob(rule, () => {
  sendWeeklyDigest();
});

One-Time Future Jobs

import schedule from 'node-schedule';

// Schedule a single future event
const launchDate = new Date(2026, 11, 31, 0, 0, 0);  // Dec 31 2026 midnight
const job = schedule.scheduleJob(launchDate, () => {
  triggerNewYearCampaign();
});

// Reschedule to a different time
job.reschedule('0 0 1 1 *');  // Every Jan 1

// job.nextInvocation() returns the next Date
console.log('Next run:', job.nextInvocation());

cron: The Original Node.js CronJob

The cron package (originally cron.js) uses a 6-field format where the first field is seconds— matching the convention used by Java Quartz and Spring @Scheduled. If you're migrating from those ecosystems, this mapping will feel natural.

Installation

npm install cron
# TypeScript types are bundled

Basic Usage

import { CronJob } from 'cron';

// 6-field: seconds minutes hours day month weekday
const job = new CronJob(
  '0 30 2 * * *',    // every day at 02:30:00
  async () => {
    await runDailyReport();
  },
  null,              // onComplete (optional)
  true,              // start immediately
  'America/New_York' // timezone
);

// Control lifecycle
job.stop();
job.start();

// Check next execution
console.log('Next:', job.nextDate().toISO());

Key Difference: Seconds-First Field Order

Comparison Table

Production Best Practices

let running = false;

cron.schedule('*/1 * * * *', async () => {
  if (running) {
    console.warn('Previous run still in progress — skipping');
    return;
  }
  running = true;
  try {
    await heavyJob();
  } finally {
    running = false;
  }
});

cron.schedule('0 2 * * *', async () => {
  try {
    await runNightlyBackup();
    logger.info('Backup completed');
  } catch (err) {
    logger.error({ err }, 'Backup failed');
    await alertOncall('Backup job failed', err);
  }
});

const tasks: cron.ScheduledTask[] = [];

tasks.push(cron.schedule('0 * * * *', hourlySync));
tasks.push(cron.schedule('0 3 * * *', dailyBackup));

// Graceful shutdown
process.on('SIGTERM', () => {
  tasks.forEach(t => t.destroy());
  process.exit(0);
});

// .env
SYNC_SCHEDULE="0 */6 * * *"
REPORT_SCHEDULE="0 8 * * 1"

// app.ts
const syncSchedule = process.env.SYNC_SCHEDULE!;
if (!cron.validate(syncSchedule)) {
  throw new Error(`Invalid SYNC_SCHEDULE: ${syncSchedule}`);
}
cron.schedule(syncSchedule, syncUsers);