Node.js Agenda tutorial – NPM package for Queue management

In Node.js Agenda tutorial, we will explore its features, provide code examples, and share helpful tips for handling jobs in your Node.js projects. Efficient queue management is critical for handling various tasks in Node.js applications. The npm package Agenda offers robust solutions for job scheduling with MongoDB. Throughout this tutorial,

Node.js Agenda tutorial

Table of Contents

Introduction to Node.js Agenda

Agenda is an npm package that leverages MongoDB to manage a job queue. It supports scheduling, running repeated jobs, and fmaintaining job priorities.


Start by installing Agenda and its peer dependency, MongoDB:

npm install agenda mongodb

Creating Jobs

Define a job and schedule it to run:

const Agenda = require('agenda');
const mongoConnectionString = 'mongodb://';

const agenda = new Agenda({db: {address: mongoConnectionString}});

agenda.define('say hello', async job => {
  console.log('Hello, World!');

async function scheduleHelloJob() {
  await agenda.start();
  await agenda.schedule('in 5 minutes', 'say hello');


When you call scheduleHelloJob, it sets up the ‘say hello’ job to execute in 5 minutes.

Repeated Jobs

Setting up a job to repeat at certain intervals:

async function scheduleRepeatedJob() {
  await agenda.start();
  await agenda.every('3 minutes', 'say hello');


This example schedules the ‘say hello’ job to run every 3 minutes.

Delayed Jobs

To delay a job’s execution, you can use the ‘schedule’ method:

async function scheduleDelayedJob() {
  await agenda.start();
  await agenda.schedule('in 10 minutes', 'say hello');


Here we scheduled the job to execute once, 10 minutes from now.

Priority and Concurrency

Agenda allows you to set priorities and concurrency limits:

agenda.define('priority job', {priority: 'high'}, async job => {
  // Job with higher priority

async function createPriorityJob() {
  await agenda.start();
  await'priority job');

agenda.define('email', {concurrency: 5}, async job => {
  // Sends an email with a limit of 5 concurrent jobs


The ‘priority job’ has a higher chance of running before other jobs. The ’email’ job can only have 5 instances running at the same time.

Pause and Resume

You can pause and resume job processing as needed:

async function pauseAndResumeJobs() {
  await agenda.start();
  await agenda.pause('say hello');

  // Later, to resume:
  await agenda.resume('say hello');


This will temporarily suspend and later resume the ‘say hello’ job queue.

Job Retries

To retry a job after a failure:

agenda.define('unstable job', async job => {
  throw new Error('unstable job failed');

agenda.on('fail:unstable job', async (err, job) => {
  if (job.attrs.failCount < 5) {
    await agenda.schedule('in 1 minute',;

This snippet retries the ‘unstable job’ up to 5 times every minute upon failure.

Global Events

Agenda emits events that allow you to react globally to job completions, failures, etc.:

agenda.on('complete', job => {
  console.log(`Job ${} finished`);

This event listener logs a message whenever any job is completed.

Job Queue Events

Similarly, you can handle events for specific jobs:

agenda.on('start:say hello', job => {
  console.log('Job say hello started');

This logs a message whenever the ‘say hello’ job starts.


If the jobs are not running as expected, check the MongoDB connection, job definitions, and ensure Agenda is started with agenda.start(). Detailed error logs can help identify issues.


Utilizing Agenda for queue management in Node.js applications allows for flexible and efficient job scheduling. By following the examples provided, you can integrate and harness the power of this npm package in managing tasks within your applications.