Getting Started
node-cron
is a lightweight task scheduler for Node.js, built in pure JavaScript and inspired by GNU crontab. It allows you to schedule tasks using full cron syntax.
Installation
Install node-cron
using npm:
npm install --save node-cron
Basic Usage
Import node-cron and schedule a task. Below are examples for both CommonJS and ES6 modules.
CommonJS
const cron = require('node-cron');
cron.schedule('* * * * *', () => {
console.log('Running a task every minute');
});
ECMAScript Modules (ESM)
import cron from 'node-cron';
cron.schedule('* * * * *', () => {
console.log('Running a task every minute');
});
The cron expression * * * * * runs the task every minute. See the Cron Syntax section for more details.
Task Context
When using an function (InlineTask) or BackgroundTask, node-cron
passes a TaskContext
object as the first argument. This object contains useful metadata about the current execution:
export type TaskContext = {
date: Date; // Scheduled server time for the tick
dateLocalIso: string; // Local ISO string for display/logging
triggeredAt: Date; // Actual execution start time
task?: ScheduledTask; // Task instance (if available)
execution?: Execution; // Execution metadata (if available)
};
Example using an inline function with context:
cron.schedule('* * * * *', async (ctx) => {
console.log(`Task started at ${ctx.triggeredAt.toISOString()}`);
console.log(`Scheduled for: ${ctx.dateLocalIso}`);
cosole.log(`Task status ${ctx.task.getStatus()}`)
});
The same may be done with background tasks:
// ./tasks/my-task.js
export function task() => {
console.log(`Task started at ${ctx.triggeredAt.toISOString()}`);
console.log(`Scheduled for: ${ctx.dateLocalIso}`);
cosole.log(`Task status ${ctx.task.getStatus()}`)
};
Use the task file path to register and start the task.
import cron from 'node-cron';
cron.schedule('*/5 * * * * *', './tasks/my-task.js');
The TaskContext
is also passed when listining task events, see more on Event Listening Guide