This post was written for Nodejitsu blog and is crossposted here. Nodejitsu loved what I was doing at and is now supporting the project.

As you web application grows, there comes a time when you will want to have scheduled jobs. The easiest thing is of course go the cron route. However, maintaining and updating it isn’t so easy, especially if you have more than one server to deal with and you still maybe too young for enterprise level job scheduler. What’s left? Maybe just do some setTimeout calls in process… That doesn’t sound very exciting nor very manageable.

This is where agenda (GitHub: rschmukler/agenda, License: MIT) by Ryan Schmukler comes in. agenda, to plainly put it, is a light-weight job scheduling library for Node.js. Lets give it a go!

npm install agenda


  • Minimal overhead. agenda aims to keep its code base small.
  • MongoDB 2.4+ backed persistance layer.
  • Scheduling with configurable priority, concurrency, and repeating.
  • Scheduling via cron or human readable syntax.
  • Event backed job queue that you can hook into.


Lets make a basic example that runs a job 10 seconds after the startup:

var Agenda = require('agenda');
var agenda = new Agenda({db: {address: 'localhost:27017/agenda-example'}});

agenda.define('greet the world', function(job, done) {
  console.log(, 'hello world!');

agenda.schedule('in 10 seconds', 'greet the world', {time: new Date()});

console.log('Wait 10 seconds...');

Check out functional example on runnable. I like plain English option, but you can also schedule regular running task with cron style expressions like so:

agenda.every('*/3 * * * *', 'greet the world');

agenda is also capable of processing jobs from multiple processes. You just have to specify lockLifetime option during the worker definition.

agenda.define('someJob', {lockLifetime: 10000}, function(job, cb) {
  //Do something in 10 seconds or less...

Mongo vs Redis

Curious why MongoDB was chosen for something most would use Redis for? Ryan Schmukler has a few thoughts on this:

The decision to use Mongo instead of Redis is intentional. Redis is often used for non-essential data (such as sessions) and without configuration doesn’t guarantee the same level of persistence as Mongo (should the server need to be restarted/crash).

agenda decides to focus on persistence without requiring special configuration of Redis (thereby degrading the performance of the Redis server on non-critical data, such as sessions).

Closing thoughts

agenda focuses on setting up and managing regular running tasks such as session purging, email sending, data processing and so on. There are a few alternatives out there: