node-cron vs cron vs node-schedule vs bull vs agenda vs later vs bree
Architecting Reliable Job Scheduling and Queue Systems in Node.js
Search packages..
node-croncronnode-schedulebullagendalaterbreeSimilar Packages:

Architecting Reliable Job Scheduling and Queue Systems in Node.js

This comparison evaluates seven prominent Node.js packages for handling time-based tasks: agenda, bree, bull, cron, later, node-cron, and node-schedule. These tools fall into two distinct architectural categories: in-process schedulers that run jobs within the current Node.js event loop (ideal for simple cron jobs or single-server setups) and persistent queue systems that rely on external databases like MongoDB or Redis to manage job state, retries, and distribution across multiple workers. Understanding the trade-offs between ease of setup, reliability during crashes, and scalability is critical for choosing the right tool for your backend infrastructure.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
node-cron8,506,7293,271328 kB4a month agoISC
cron6,726,2958,947161 kB448 months agoMIT
node-schedule4,562,7469,20735 kB1734 years agoMIT
bull1,609,65816,247309 kB1472 years agoMIT
agenda186,2659,691301 kB4916 days agoMIT
later43,7282,406-9811 years agoMIT
bree03,29092 kB296 months agoMIT

Architecting Reliable Job Scheduling and Queue Systems in Node.js

When building backend services in Node.js, handling delayed tasks, recurring jobs, and background processing is a common requirement. The ecosystem offers several solutions, ranging from simple in-process timers to robust, distributed queue systems. The choice between packages like agenda, bree, bull, cron, later, node-cron, and node-schedule fundamentally depends on whether you need persistence and distribution or just simple scheduling.

Let's break down these tools by their architectural patterns, execution models, and real-world usage.

🏗️ Architecture: Persistent Queues vs. In-Process Schedulers

The most critical decision is whether your jobs need to survive a server crash or run across multiple servers.

Persistent Queues (Database-Backed)

agenda and bull store job definitions and states in an external database. This ensures that if your server crashes, pending jobs are not lost and can be picked up by another worker.

agenda uses MongoDB to store jobs. It acts as both the scheduler and the processor.

// agenda: Define and schedule a job
const agenda = new Agenda({ db: { address: 'mongodb://localhost/agenda' } });

agenda.define('send email', async (job) => {
  await sendEmail(job.attrs.data.to);
});

await agenda.start();
await agenda.every('10 minutes', 'send email', { to: 'user@example.com' });

bull uses Redis to manage highly performant queues. It separates the concept of producing jobs (adding to the queue) and consuming them (workers processing them).

// bull: Create a queue and add a job
const Queue = require('bull');
const emailQueue = new Queue('email tasks', 'redis://127.0.0.1:6379');

emailQueue.add({ to: 'user@example.com' }, { attempts: 3, backoff: 5000 });

// Worker process
emailQueue.process(async (job) => {
  await sendEmail(job.data.to);
});

In-Process Schedulers (Memory-Only)

node-cron, node-schedule, bree, and cron run entirely within the Node.js process memory. If the process dies, scheduled jobs are lost unless you have external logic to re-queue them.

node-cron is a lightweight implementation of standard cron syntax.

// node-cron: Simple cron job
const cron = require('node-cron');

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

node-schedule offers more flexibility than standard cron, allowing you to schedule jobs for specific dates or using rule-based logic.

// node-schedule: Schedule for a specific date or rule
const schedule = require('node-schedule');

// Run at 4:30 AM every day
const job = schedule.scheduleJob('4 30 * * *', () => {
  console.log('Good morning!');
});

// Or run at a specific Date object
const futureDate = new Date(Date.now() + 60000);
schedule.scheduleJob(futureDate, () => {
  console.log('Ran after 1 minute');
});

bree takes a different approach by managing jobs as separate files that run in worker threads or child processes, preventing long-running tasks from blocking the main event loop.

// bree: Configure and start
const Bree = require('bree');

const bree = new Bree({
  root: './jobs', // Directory containing job files
  jobs: [
    { name: 'clean-up', interval: 'every 5 minutes' },
    { name: 'report', cron: '0 0 * * *' }
  ]
});

bree.start();

⏱️ Scheduling Syntax and Flexibility

How you define "when" a job runs varies significantly between these libraries.

cron and node-cron strictly adhere to standard Unix cron syntax (minute, hour, day, month, weekday). This is familiar to DevOps engineers but can be limiting for complex intervals like "every 90 minutes."

// cron / node-cron: Standard syntax only
// This works: Every hour
job.schedule('0 * * * *');

// This is hard: Every 90 minutes requires complex cron math
job.schedule('0 */90 * * *'); // Incorrect logic for 90 mins across hours

node-schedule supports cron syntax but also allows for RecurrenceRule objects and natural language-like intervals, making it easier to express non-standard timings.

// node-schedule: Flexible rules
const rule = new schedule.RecurrenceRule();
rule.minute = 0;
rule.hour = 2;
rule.dayOfWeek = 1; // Mondays

schedule.scheduleJob(rule, () => {
  console.log('Every Monday at 2 AM');
});

agenda uses human-readable strings powered by the human-interval and cron-parser libraries, offering the most readable syntax for business logic.

// agenda: Human readable
await agenda.every('5 minutes', 'calculate stats');
await agenda.schedule('in 2 hours', 'send reminder', { userId: 123 });
await agenda.schedule('tomorrow at noon', 'daily report');

bree supports both cron syntax and human-readable intervals (via human-interval), combining flexibility with its worker-thread architecture.

// bree: Mixed syntax support
jobs: [
  { name: 'task1', interval: 'every 5 minutes' },
  { name: 'task2', cron: '0 12 * * *' }
]

later was famous for its extremely flexible scheduling logic, allowing complex combinations of time constraints. However, due to its deprecated status, it should not be used in new projects.

// later: (Deprecated) Complex scheduling example
// DO NOT USE IN NEW PROJECTS
const schedule = later.schedule(later.parse.cron('*/5 * * * *'));

🛡️ Reliability and Concurrency Control

When running jobs in production, you must handle failures, concurrency, and server restarts.

Handling Crashes and Restarts

bull and agenda excel here. Since job state is in Redis or MongoDB, if a worker crashes while processing a job, the system detects the timeout and can re-queue the job automatically.

// bull: Automatic retry on failure
queue.add({ data }, {
  attempts: 3,
  backoff: {
    type: 'exponential',
    delay: 1000
  }
});

In contrast, node-cron and node-schedule have no built-in recovery. If the server restarts, you must rely on the code re-executing the schedule definition on startup. They also lack built-in mechanisms to detect if a job is stuck.

Concurrency and Blocking

A common pitfall in Node.js is running heavy CPU tasks in the main event loop, which blocks incoming requests.

bree solves this by design. Each job runs in a separate worker thread or child process. This isolates crashes and prevents CPU-heavy tasks from freezing your API.

// bree: Job runs in isolated worker (jobs/clean-up.js)
module.exports = async () => {
  // Heavy CPU usage here won't block the main scheduler
  performHeavyCalculation();
};

bull also encourages running workers in separate processes or even on different servers, naturally isolating the load.

agenda, node-cron, and node-schedule run jobs in the main thread by default. You must manually spawn child processes or worker threads if your jobs are CPU-intensive.

// node-schedule: Manual worker spawning required for heavy tasks
schedule.scheduleJob('*/5 * * * *', () => {
  const worker = new Worker('./heavy-task.js');
  worker.on('message', (result) => console.log(result));
});

🚫 Deprecation Warning: later

It is crucial to note that later is no longer actively maintained. The repository has seen minimal activity in recent years, and it does not align well with modern Node.js practices. Using it introduces security risks and potential compatibility issues with newer Node versions. For any logic requiring complex scheduling, node-schedule or agenda are the recommended modern alternatives.

📊 Summary Comparison

Featureagendabullbreenode-cronnode-schedulecronlater
StorageMongoDBRedisMemory / FilesMemoryMemoryMemoryMemory
Persistence✅ Yes✅ Yes❌ No❌ No❌ No❌ No❌ No
Distributed✅ Yes✅ Yes❌ No❌ No❌ No❌ No❌ No
IsolationMain ThreadExternal WorkerWorker ThreadMain ThreadMain ThreadMain ThreadMain Thread
SyntaxHuman/CronCron/ConfigHuman/CronCronCron/RulesCronComplex
StatusActiveActiveActiveActiveActiveActive⚠️ Deprecated

💡 Final Recommendation

Your choice should depend on the criticality of the jobs and your infrastructure:

  1. For Mission-Critical Background Jobs: Use bull if you have Redis, or agenda if you prefer MongoDB. These provide the necessary safety nets for retries, persistence, and distributed processing.
  2. For CPU-Intensive Scheduled Tasks: Use bree. Its worker-thread architecture is uniquely suited for preventing event-loop blocking without the complexity of setting up a full queue system.
  3. For Simple, Single-Server Cron Jobs: Use node-cron for standard needs or node-schedule if you need more flexible timing rules. They are lightweight and easy to implement for non-critical tasks like cache warming or log rotation.
  4. Avoid: Do not start new projects with later. Its lack of maintenance makes it a liability compared to the robust alternatives available today.

How to Choose: node-cron vs cron vs node-schedule vs bull vs agenda vs later vs bree

  • node-cron:

    Choose node-cron if you need a straightforward, zero-dependency implementation of cron syntax for in-process scheduling. It is perfect for simple tasks like cleaning up logs or sending daily emails on a single server instance. Do not use it if you need job persistence, distributed execution, or protection against server crashes, as jobs are lost when the process dies.

  • cron:

    Choose cron (often installed as cron or node-cron depending on context, but here referring to the specific implementation) if you need a pure JavaScript cron parser with no external dependencies for simple, in-process scheduling. It is suitable for lightweight tasks on a single server where job persistence across restarts is not required. Note that this package is often confused with node-cron; ensure you select the one with active maintenance for your specific syntax needs.

  • node-schedule:

    Choose node-schedule if you need flexible scheduling beyond standard cron syntax, such as firing jobs based on specific dates, times, or natural language rules (e.g., 'every 2 hours'). It is an in-process scheduler ideal for applications that require complex timing logic without the overhead of external databases. Like other in-process tools, it does not support distributed job locking or persistence across restarts.

  • bull:

    Choose bull if you require a high-performance, distributed job queue with advanced features like priority queues, rate limiting, and automatic retries backed by Redis. It is the industry standard for heavy-duty background processing where reliability and scalability are paramount. Avoid it if you cannot introduce Redis as a dependency or if your use case is limited to simple, single-server cron jobs.

  • agenda:

    Choose agenda if you need a robust, database-backed job queue with human-readable scheduling syntax and are already using MongoDB. It excels in scenarios requiring job persistence, retries, and locking mechanisms to prevent duplicate execution across multiple server instances. However, avoid it if you cannot tolerate the overhead of database connections for every job check or if your project does not already depend on MongoDB.

  • later:

    Avoid using later for new projects as it is largely deprecated and unmaintained. While it historically offered powerful human-readable scheduling logic, its lack of updates poses security and compatibility risks. Modern alternatives like node-schedule or bree provide similar or superior functionality with active support and better integration with current Node.js versions.

  • bree:

    Choose bree if you prefer a modern, lightweight scheduler that runs jobs in separate worker threads or processes to prevent blocking the main event loop. It is ideal for CPU-intensive tasks or when you want strict isolation between jobs without the complexity of setting up Redis or MongoDB. It supports cron syntax and simple intervals but lacks the advanced distributed queue features of bull or agenda.

Similar Npm Packages to node-cron

node-cron is a popular npm package that allows developers to schedule tasks in Node.js applications using cron syntax. It provides a simple and flexible way to run recurring jobs at specified intervals, making it ideal for tasks such as sending emails, cleaning up databases, or performing regular data processing. With its straightforward API, node-cron is easy to integrate into existing applications and can handle complex scheduling needs with ease.

However, there are several alternatives to node-cron that also provide task scheduling capabilities in Node.js. Here are a couple of notable options:

  • cron is a lightweight and flexible library for scheduling tasks in Node.js. It allows you to create cron jobs using a simple API and supports various scheduling patterns. The cron package is particularly useful for developers who prefer a more minimalistic approach to task scheduling without additional features that may not be necessary for their use case. It is a solid choice for those who need basic cron functionality without the overhead of more complex libraries.

  • node-schedule is another powerful scheduling library for Node.js that allows you to schedule jobs using both cron syntax and JavaScript Date objects. It provides a more advanced scheduling mechanism compared to node-cron, allowing for more complex scheduling scenarios, such as scheduling tasks based on specific dates or intervals. If your application requires more sophisticated scheduling capabilities, node-schedule is an excellent alternative to consider.

To see how these packages compare, check out the comparison: Comparing cron vs node-cron vs node-schedule.

Similar Npm Packages to cron

cron is a popular Node.js package that allows developers to schedule and manage recurring tasks using cron syntax. It provides a straightforward API for defining job schedules and executing tasks at specified intervals, making it an excellent choice for applications that require timed operations, such as sending emails, cleaning up databases, or performing regular data synchronization. With its robust features and ease of use, cron has become a go-to solution for task scheduling in Node.js applications.

However, there are several alternatives to cron that offer different features and capabilities:

  • agenda is a lightweight job scheduling library for Node.js that uses MongoDB as its backend for storing job data. It allows developers to define jobs with a flexible syntax and provides features such as job prioritization, delayed jobs, and recurring jobs. If your application already uses MongoDB and you need a more feature-rich scheduling solution, agenda is an excellent choice that integrates seamlessly with your existing database.
  • later is another scheduling library for Node.js that provides a more flexible and powerful way to define schedules. It allows developers to create complex schedules using a variety of formats, including cron-like syntax and more human-readable expressions. later is particularly useful for applications that require intricate scheduling logic, as it can handle a wide range of scheduling scenarios with ease.
  • node-cron is a simple and lightweight cron-like job scheduler for Node.js. It provides a straightforward API for scheduling tasks using cron syntax and is designed to be easy to use and integrate into existing applications. If you are looking for a minimalistic alternative to cron that still offers the core functionality of scheduling tasks, node-cron is a solid option.

To explore how these packages compare, check out the following link: Comparing agenda vs cron vs later vs node-cron.

Similar Npm Packages to node-schedule

node-schedule is a flexible and easy-to-use job scheduling library for Node.js. It allows developers to schedule tasks to run at specific times or intervals, making it ideal for automating repetitive tasks, sending notifications, or performing maintenance operations. While node-schedule is a robust solution for scheduling jobs, there are several alternatives available in the Node.js ecosystem. Here are a few noteworthy options:

  • agenda is a lightweight job scheduling library for Node.js that uses MongoDB as its backend. It provides a simple API for defining jobs and scheduling them to run at specific times or intervals. Agenda is particularly useful for applications that require persistent job storage and management, as it allows you to keep track of job states and results in a MongoDB database. If your application already uses MongoDB and you need a reliable way to schedule jobs, Agenda is a strong choice.

  • cron is a popular library for scheduling tasks in Node.js using cron syntax. It allows developers to define jobs that run at specific times based on a cron expression, making it easy to schedule tasks with complex timing requirements. If you are familiar with cron jobs from Unix-like systems and want to leverage that knowledge in your Node.js applications, the cron library is an excellent option.

  • later is another scheduling library for Node.js that provides a more flexible scheduling syntax compared to traditional cron expressions. It allows you to define schedules using a variety of formats, including intervals, specific times, and even complex recurring patterns. Later is particularly useful if you need to create intricate scheduling logic without being constrained by the limitations of cron syntax.

  • node-cron is a simple and lightweight cron-like job scheduler for Node.js. It allows you to schedule tasks using cron syntax, similar to the cron library. Node-cron is easy to set up and use, making it a great choice for developers who want a straightforward solution for scheduling tasks without the need for additional complexity.

To explore how node-schedule compares with agenda, cron, later, and node-cron, check out the comparison: Comparing agenda vs cron vs later vs node-cron vs node-schedule.

Similar Npm Packages to bull

bull is a robust queue library for Node.js, designed to handle distributed jobs and messages in a scalable manner. It is built on top of Redis and provides a simple API for creating and managing job queues. Bull is particularly useful for applications that require background processing, such as sending emails, processing images, or handling other time-consuming tasks. With features like job retries, delayed jobs, and concurrency control, Bull makes it easy to manage complex workflows efficiently.

While Bull is a popular choice for job and queue management, there are several alternatives that cater to different needs and preferences:

  • agenda is a lightweight job scheduling library for Node.js that uses MongoDB as its backend. It allows you to schedule jobs to run at specific times or intervals, making it suitable for applications that require cron-like functionality. Agenda is easy to set up and provides a simple API for defining and managing jobs, making it a good choice for applications that already use MongoDB and need a straightforward scheduling solution.

  • bee-queue is another lightweight queue library for Node.js that focuses on simplicity and performance. It is designed for handling jobs in a single Redis instance and provides a minimalistic API for creating and processing jobs. Bee-Queue is particularly well-suited for applications that require fast job processing with low overhead, making it a great alternative for developers looking for a straightforward queuing solution.

  • bullmq is the successor to Bull, offering a more modern and feature-rich approach to job and queue management. It introduces a new architecture and API, providing improved performance and additional features such as rate limiting, job prioritization, and more. If you are starting a new project or looking to upgrade from Bull, BullMQ is the recommended choice for its enhanced capabilities and flexibility.

  • kue is a priority job queue backed by Redis, designed for handling distributed jobs in Node.js applications. It provides a rich set of features, including job prioritization, delayed jobs, and a user interface for monitoring job progress. Kue is suitable for applications that require a more comprehensive job management solution with a focus on monitoring and visualization.

  • node-resque is a Redis-backed library for creating background jobs in Node.js. It supports multiple backends and provides a flexible API for defining and managing jobs. Node-resque is ideal for applications that need a customizable job processing solution and want to leverage the power of Redis for job management.

To explore how these libraries compare, check out the following link: Comparing agenda vs bee-queue vs bull vs bullmq vs kue vs node-resque.

Similar Npm Packages to agenda

agenda is a job scheduling library for Node.js that allows developers to manage and execute background jobs easily. It is built on top of MongoDB, enabling persistent job storage and providing a flexible API for scheduling tasks. With agenda, you can define recurring jobs, manage job priorities, and handle job failures gracefully. This makes it a great choice for applications that require reliable job scheduling and processing.

While agenda is a powerful tool, there are several alternatives available in the Node.js ecosystem that also provide job scheduling capabilities. Here are a couple of notable alternatives:

  • bull is a robust queue and job scheduling library for Node.js that is built on Redis. It offers a rich set of features, including delayed jobs, job retries, and concurrency control. Bull is particularly well-suited for applications that need to handle a high volume of jobs or require advanced job management capabilities. Its performance and reliability make it a popular choice for developers looking to implement job queues in their applications.

  • node-schedule is a flexible job scheduling library for Node.js that allows you to schedule jobs using cron-like syntax. It is lightweight and easy to use, making it ideal for applications that require simple scheduling without the overhead of a persistent job store. Node-schedule is perfect for scenarios where you need to run tasks at specific intervals or times without the need for complex job management features.

To see how agenda compares with bull and node-schedule, check out the comparison: Comparing agenda vs bull vs node-schedule.

Similar Npm Packages to later

later is a scheduling library for JavaScript that allows developers to schedule tasks with ease. It provides a flexible and powerful way to define recurring events and manage time-based operations. While later is a great option for scheduling tasks, there are several alternatives in the Node.js ecosystem that also offer scheduling capabilities. Here are a few notable alternatives:

  • agenda is a lightweight job scheduling library for Node.js that uses MongoDB as a backend. It allows you to define jobs and schedule them to run at specific times or intervals. Agenda is particularly useful for applications that require persistent job storage and management, making it an excellent choice for applications that need to handle background tasks or delayed jobs. With its simple API and built-in support for job retries and concurrency, agenda is a robust solution for task scheduling in Node.js applications.
  • cron is a popular library that allows you to schedule tasks using cron syntax. It provides a straightforward way to run tasks at specific times or intervals, similar to the Unix cron jobs. If you are familiar with cron syntax and need a simple way to schedule tasks in your Node.js application, the cron library is a great choice. Its lightweight nature and ease of use make it suitable for a variety of scheduling needs.
  • node-schedule is another flexible scheduling library for Node.js that allows you to schedule jobs using cron-like syntax or JavaScript Date objects. It provides a simple API for scheduling tasks and supports recurring jobs, making it a versatile option for various scheduling scenarios. If you need a library that combines the simplicity of cron syntax with the flexibility of JavaScript date handling, node-schedule is an excellent choice.

To see how later compares with agenda, cron, and node-schedule, check out the comparison: Comparing agenda vs cron vs later vs node-schedule.

Similar Npm Packages to bree

bree is a job scheduling library for Node.js that allows developers to run background tasks and scheduled jobs with ease. It is designed to be simple and efficient, providing a straightforward API for scheduling tasks at specific intervals or times. Bree supports both cron-like scheduling and more complex job scheduling scenarios, making it a versatile choice for managing background tasks in Node.js applications.

While Bree is a powerful tool for job scheduling, there are several alternatives in the Node.js ecosystem that offer similar functionalities. Here are a few notable options:

  • agenda is a lightweight job scheduling library for Node.js that uses MongoDB as its persistence layer. It provides a simple API for scheduling jobs and supports recurring jobs, delayed jobs, and more. Agenda is a great choice if you are already using MongoDB in your application and want a seamless way to manage background tasks without introducing additional dependencies.

  • bull is a robust job and message queue library for Node.js that is built on Redis. It offers advanced features such as job prioritization, delayed jobs, and concurrency control. Bull is ideal for applications that require high performance and reliability in job processing, especially when dealing with a large number of jobs or complex workflows.

  • cron is a simple and straightforward library for scheduling tasks using cron syntax. It allows you to run tasks at specific intervals defined by cron expressions. If you are looking for a lightweight solution for running scheduled tasks without the overhead of a full job queue, cron is a solid choice.

  • later is a flexible scheduling library that allows you to define schedules using a variety of formats, including cron-like syntax. It provides a powerful API for scheduling tasks and can handle complex scheduling scenarios. Later is suitable for applications that require advanced scheduling capabilities beyond standard cron expressions.

  • node-cron is another simple cron-based job scheduler for Node.js. It allows you to schedule tasks using cron syntax and is easy to integrate into existing applications. Node-cron is a good option for developers who prefer a straightforward approach to scheduling tasks without additional complexity.

  • node-schedule is a flexible job scheduling library for Node.js that allows you to schedule jobs using cron-like syntax or JavaScript Date objects. It supports recurring jobs and provides a simple API for managing scheduled tasks. Node-schedule is a great choice for applications that need a flexible and easy-to-use scheduling solution.

To see how Bree compares with these alternatives, check out the comparison: Comparing agenda vs bree vs bull vs cron vs later vs node-cron vs node-schedule.

README for node-cron

Node Cron

npm version npm downloads used by coverage zero dependencies license sponsor

Job scheduling for Node.js with overlap prevention, distributed coordination, and background tasks. Schedule recurring tasks with cron expressions, prevent overlapping runs, coordinate across multiple instances, and run heavy jobs in isolated background processes. Zero dependencies, written in TypeScript.

Full documentation: nodecron.com

Getting Started

npm install node-cron

import cron from 'node-cron';

cron.schedule('* * * * *', () => {
  console.log('running a task every minute');
});

Overlap Prevention

Long-running tasks can overlap when the next tick fires before the previous run finishes. noOverlap skips a run instead of stacking them:

cron.schedule('* * * * *', async () => {
  await slowJob();
}, { noOverlap: true });

Distributed Coordination

Running multiple instances of your app? distributed: true ensures only one instance executes each scheduled fire. Out of the box it uses an env-var flag; for high availability, plug in a Redis coordinator:

cron.schedule('0 3 * * *', runNightlyBackup, {
  name: 'nightly-backup',
  distributed: true,
});

Background Tasks

Pass a file path instead of a function to run a job in an isolated forked process, so heavy work never blocks your event loop:

cron.schedule('0 3 * * *', './tasks/backup.js');

Bundlers: background tasks fork a helper that node-cron resolves relative to its own files in node_modules. If you bundle your app (esbuild, webpack, Rollup, etc.), mark node-cron as external so it stays on disk (--external:node-cron, or externals: ['node-cron'] in webpack). Otherwise the fork fails with Cannot find module '.../daemon.js'. Inline function tasks are unaffected.

Runtime Control

Every task exposes a single consistent interface for control and inspection:

const task = cron.schedule('0 3 * * *', doWork, {
  name: 'nightly-backup',
  timezone: 'America/Sao_Paulo',
});

task.stop();          // pause
task.start();         // resume
task.destroy();       // remove permanently
task.getStatus();     // 'stopped' | 'idle' | 'running' | 'destroyed'
task.getNextRun();    // next scheduled Date, or null
task.lastRun();       // { date, result } or { date, error }, or null

Events

Tasks emit lifecycle events for observability:

task.on('execution:finished', (ctx) => console.log('result:', ctx.execution?.result));
task.on('execution:failed', (ctx) => console.error('failed:', ctx.execution?.error));
task.on('execution:overlap', () => console.warn('skipped: previous run still active'));
task.on('execution:skipped', (ctx) => console.log('not elected:', ctx.reason));
task.on('task:failed', () => task.start()); // background task's daemon died unexpectedly (crash, OOM-kill); restart manually

All events: task:started, task:stopped, task:destroyed, task:failed, execution:started, execution:finished, execution:failed, execution:missed, execution:overlap, execution:maxReached, execution:skipped. See Events & Observability.

Cron Syntax

 # ┌────────────── second (optional)
 # │ ┌──────────── minute
 # │ │ ┌────────── hour
 # │ │ │ ┌──────── day of month
 # │ │ │ │ ┌────── month
 # │ │ │ │ │ ┌──── day of week
 # │ │ │ │ │ │
 # * * * * * *
fieldvalue
second0-59 (optional)
minute0-59
hour0-23
day of month1-31 (or L for the last day; L-3 offset from last; 15W, LW for nearest weekday)
month1-12 (or names)
day of week0-7 (or names, 0 or 7 are Sunday; 2#3, 5L)

Supports ranges (1-5), steps (*/2), lists (1,15), named months/weekdays, L (last day of month), L-n (offset from the last day), # (nth weekday), <weekday>L (last weekday of month), W (nearest weekday), and ? (alias for * in the day fields, for Quartz-style expressions). See the Cron Syntax guide.

An inverted range wraps around the field instead of being rejected: 22-2 in the hour field means 22:00 through 02:59 (22,23,0,1,2), and sat-sun in the day-of-week field means saturday,sunday.

The W modifier in the day-of-month field fires on the nearest weekday (Monday-Friday) to a given day, without crossing the month boundary: 15W is the nearest weekday to the 15th, 1W the first weekday of the month, and LW the last weekday of the month. Only weekends are adjusted for; there is no holiday awareness.

The L-n form fires n days before the last day of the month (L-3 is the third-to-last day). In months where the offset reaches before the 1st (e.g. L-29 in February), it simply does not fire that month.

Note on Quartz: L, L-n, W, LW, #, <weekday>L and ? are borrowed from Quartz, but node-cron is not Quartz-compatible. Two differences matter:

  • Day-of-week numbering is standard cron, not Quartz: 0-7 with 0/7 = Sunday and 1 = Monday. In Quartz 1 = Sunday, so the same numeric weekday fires on a different day.
  • day-of-month and day-of-week are combined with AND (both must match), and may both be set; Quartz instead treats them as mutually exclusive and requires ? in one of them.

? is accepted purely as an alias for * in the day fields so Quartz-style expressions parse, not as a semantic compatibility guarantee.

When to Use node-cron

  • Recurring jobs on a schedule (cron expressions with second-level precision)
  • Overlap prevention for long-running tasks
  • Coordinating scheduled tasks across multiple instances or replicas
  • Running heavy jobs in isolated background processes
  • Runtime control: start, stop, inspect, and observe tasks programmatically

When to Consider Something Else

  • Durable job queues with retries and priorities: use BullMQ, Agenda, or Sidequest
  • Persistent workflow orchestration: use Temporal or Inngest
  • Exactly-once guarantees across crashes: node-cron coordinates but does not persist state to a database; a queue or workflow engine is a better fit

Options

cron.schedule('0 3 * * *', task, {
  name: 'nightly-backup',
  timezone: 'America/Sao_Paulo',
  noOverlap: true,
  distributed: true,
  maxExecutions: 10,
  maxRandomDelay: 30000,
});

See Scheduling Options for the full list.

Timezones and DST

Schedules match wall-clock time in the task's timezone. Across a daylight-saving fall-back the repeated hour runs once, so a sub-hourly schedule (for example */15) can pause for up to the length of the DST shift during that hour. If you need a fixed interval to keep firing uninterrupted across DST transitions, use a zone without DST, for example timezone: 'UTC'. See Timezones & DST for the full model.

Migrating from v3

v4 is a TypeScript rewrite with a smarter scheduler and a streamlined API. See the Migration Guide.

Sponsors

node-cron is zero-dependency infrastructure used in production by 220,000+ repositories. If it is part of your stack, sponsoring helps keep it tested, DST-correct, and maintained.

Silver sponsors
easySAAS

Become a sponsor on GitHub Sponsors or Open Collective.

Issues

Feel free to submit issues and enhancement requests here.

Contributing

In general, we follow the "fork-and-pull" Git workflow.

  • Fork the repo on GitHub;
  • Commit changes to a branch in your fork;
  • Pull request "upstream" with your changes;

NOTE: Be sure to merge the latest from "upstream" before making a pull request!

Please do not contribute code you did not write yourself, unless you are certain you have the legal ability to do so. Also ensure all contributed code can be distributed under the ISC License.

License

node-cron is under ISC License.

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. For more details, please refer to our Terms & Privacy.