How to Schedule and Run Recurring Cron Jobs in Node.JS

It's a common requirement in programming to have to set something up to run at certain intervals. For example, you might want to process a database every 30 minutes, or you might want to send an email once a week. The way we typically do this is with cron jobs. In Node.JS, we can also set up cron jobs to run at specific intervals. Let's look at how it works.

How Cron Jobs Work in Node.JS

The best way to create a cron job in Node.JS is to use a package called node-schedule. Make sure you have Node.JS installed, and then run the following command in your project folder to install it:

npm i node-schedule

node-schedule essentially allows us to set up recurring jobs using the cron format of timing. The cron format is a set of 6 characters in Javascript, where each represents a different element of time. We can use asterisks as wild cards, as well. The order of the format looks like this:

*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    │
│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    │    └───── month (1 - 12)
│    │    │    └────────── day of month (1 - 31)
│    │    └─────────────── hour (0 - 23)
│    └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, OPTIONAL)

The easiest way to understand the cron format is that if we give the most basic format, that being * * * * *, it is translated as meaning every day of the week of every month of every day of month of every hour of every minute of every second. So essentially, * * * * * runs every second in node-schedule.

If we start defining numbers instead of stars, then we can start to limit how often something occurs. For example, 00 30 10 * * 1 will define a job that runs on the first day of the week, on every month, on every day of the month, when the hour is 10, the minutes are 30, and the seconds are 00.

So essentially, this job will run every week, on Monday, at 10:30 am.

Other Symbols Used in Cron Jobs

There are also a few other symbols we can use in cron jobs, which can be confusing when you first see them.

• dash (-) - can be used to represent a range, for example, 2-5 representing 2,3,4,5. Example: 00 30 10 * * 1-4.

• question mark (?) - can be used in day of week or day of month, if one doesn't matter. For example, if we want something to fire on a specific day of the month, but we don't care what day of the week it is - then we set the day of week to ?. Example: 00 30 10 * * ?.

• forward slash (/) - used for defining series. For example, giving */5 for the value of the hour represents 0,5,10,15,20. If you give a number as the first argument, it defines the starting number, i.e., 2/5 in the hour field represents 2,7,12,17,22. Example: 00 30 */5 * * 1.

• comma (,) - for a series of numbers, i.e., 2,3,5,7. Example: 00 30 5 * 4,5,6 1.

Setting up a cron job in Node.JS

Now that we understand a bit about how to format cron jobs, let's look at how to create one. Let's say we want to use our earlier example and create a cron job that runs every Monday at 10:30am. The format we will use is 00 30 10 * * 1. Make a file called scheduler.js in your project, and put the following code inside:

import schedule from 'node-schedule'
schedule.scheduleJob('00 30 10 * * 1', async function() {
    // This will run every Monday at 10:30;
    console.log('hey!');
});

Anything within function() ... above will run every Monday at 10:30 am. In this case, console.log('hey!'). To start the script, you can run it straight from the command line like so:

node scheduler.js

Now, our job will run any time it is Monday, and the time is 10:30 am.

Persistently Running Cron Jobs in Node.JS

This code is fine, but it means you have to keep your node scheduler.js session live. If you want to run a cron job like this in the background without having to worry about it, it's better to use pm2 to keep it running persistently. pm2 starts up a Node.JS program, and keeps it running so you don't have to worry about it. You can install pm2 with the following line in terminal:

npm install pm2 -g

Then, to run your scheduler.js file and keep it running persistently, run the following command in the terminal:

pm2 start scheduler.js

Now, our scheduler.js file is running in the background and will fire off every Monday at 10:30 am - so you don't have to worry about it.

Conclusion

Cron job requirements come up all the time, so it's really useful to have this functionality within Node.JS. Cron jobs can be used to do so many things, like tidy up file structures, send emails, or process large sets of data at recurring intervals. I hope you've enjoyed this guide.