/
Application Framework

node-cron Guide

node-cron is the most widely used npm package for in-process job scheduling in Node.js applications — it parses standard cron syntax and runs your callback function on schedule, entirely inside your existing Node process, without needing the OS's own cron daemon.

Syntax Notes

Supports standard 5-field cron syntax, plus an optional 6th leading seconds field if you need sub-minute precision. Runs entirely in-process — the schedule only exists while your Node application is running.

Examples

Basic scheduled task
const cron = require('node-cron');

cron.schedule('*/5 * * * *', () => {
  console.log('Running every 5 minutes');
});
With an explicit timezone
cron.schedule('0 9 * * 1-5', () => {
  sendDailyReport();
}, {
  timezone: 'America/New_York',
});

Gotchas

  • Because node-cron runs in-process, the schedule stops entirely if the Node process crashes or restarts — unlike system cron, there's no separate daemon keeping the schedule alive independent of your application's uptime.
  • Running multiple instances of your app (common in horizontally-scaled deployments) means the scheduled task fires once per instance, not once total — without external coordination (a lock, a dedicated scheduler instance, or a distributed lock), the same job can run N times simultaneously.
  • node-cron validates the cron string at `schedule()` call time and throws synchronously if it's invalid — an unhandled exception here can crash the whole process at startup if the validation isn't wrapped defensively.

Best Practices

  • In any horizontally-scaled deployment, either run scheduled jobs from a single dedicated instance/process, or use a distributed lock (Redis-based, for example) so only one instance actually executes the task per scheduled time.
  • Wrap the scheduled callback's body in a try/catch — an uncaught exception inside the callback can otherwise crash the whole process depending on your error-handling setup, taking down more than just the scheduled task.
  • Set the `timezone` option explicitly rather than relying on the server's local timezone, especially for anything deployed across multiple regions.

Frequently Asked Questions

Does node-cron persist schedules across restarts?
No — the schedule only exists in memory while the Node process is running. If the process restarts, `cron.schedule()` needs to be called again (typically at application startup) to re-register the job.
Can node-cron run tasks more precisely than once a minute?
Yes, via the optional 6-field syntax with a leading seconds field, giving second-level granularity if your Node event loop can keep up with it.
What happens if two instances of my app both run the same node-cron schedule?
Both will fire independently at the scheduled time, effectively running the job twice (or N times for N instances) — node-cron has no built-in cross-instance coordination, so you need external locking for anything that shouldn't run more than once.