Setting Up Queue Jobs in AdonisJS v6 with BullMQ

Job queues are essential in modern applications to handle background tasks efficiently, ensuring a smooth user experience by offloading time-consuming operations. AdonisJS v6 provides robust support for job processing using BullMQ. In this guide, we will walk through setting up queue jobs in AdonisJS, creating and dispatching jobs, and setting up a dashboard to monitor your job queues.

Prerequisites

Before diving into the setup, ensure that you have:

• AdonisJS v6 installed.

• Node.js and a package manager like npm.

• Redis is installed and running, as BullMQ requires Redis for job management.

---

Installing AdonisJS Jobs Package

The adonisjs-jobs package integrates BullMQ with AdonisJS, simplifying job creation and management.

Step 1: Install the Package

Use the following command to install the package via npm:

npm install adonisjs-jobs

Step 2: Configure the Package

Run the configuration command to set up the package in your project:

node ace configure adonisjs-jobs

This command will generate the necessary configuration files for managing jobs.

---

Creating Jobs

AdonisJS makes it simple to create new job classes.

Step 1: Generate a Job

Run the following command to create a new job:

node ace jobs:make SendEmail

This will generate a new job file in the app/jobs directory, where you can define the logic for your background task.

Example: SendEmail Job

export default class SendEmail {
  public static async handle(data) {
    // Logic to send email
    console.log(`Sending email to: ${data.email}`);
  }
}

---

Listening for Jobs

To process jobs, you need to start the job listener. AdonisJS supports multiple listeners for concurrent job processing.

Default Listener

Run the default job listener with the following command:

node ace jobs:listen

This listens to the default queue specified in the REDIS_QUEUE environment variable.

Custom Queues

You can specify custom queues and concurrency levels:

node ace jobs:listen --queue=high
node ace jobs:listen --queue=high,medium,low
node ace jobs:listen --queue=high --concurrency=3

Running the Worker in Production

To run the job listener in a production environment after building your application, you can use PM2:

pm2 start "node ace jobs:listen"

This ensures your job listener runs as a background process and restarts automatically if it fails.

---

Dispatching Jobs

Once your job class is ready, you can dispatch jobs programmatically in your application.

Basic Dispatch

Import the job class and dispatch a job:

import SendEmail from 'path/to/jobs/send_email.js';

await SendEmail.dispatch({ email: 'user@example.com' });

Advanced Options

You can configure job options like attempts and delays:

await SendEmail.dispatch({ email: 'user@example.com' }, {
  attempts: 3,
  delay: 1000, // 1 second delay
});

For more options, refer to the BullMQ documentation.

---

Using Import Aliases (Optional)

To simplify imports, you can configure aliases for your job files.

Update package.json

Add the following alias to your package.json:

{
  "imports": {
    "#jobs/*": "./app/jobs/*.js"
  }
}

Update tsconfig.json

Add the path configuration to your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "#jobs/*": ["./app/jobs/*.js"]
    }
  }
}

Now you can import jobs using aliases:

import SendEmail from '#jobs/send_email.js';

await SendEmail.dispatch({ email: 'user@example.com' });

---

Setting Up a Jobs Dashboard

Monitoring job queues is crucial for debugging and performance optimization. AdonisJS allows you to set up a dashboard to view job statuses.

Step 1: Add a Route for the Dashboard

In your start/routes.ts file, add the following:

import router from '@adonisjs/core/services/router';

router.jobs(); // Default route is /jobs

You can customize the route path:

router.jobs('/my-jobs-dashboard');

Step 2: Add Middleware (Optional)

To secure the dashboard, add middleware to the route group:

router.jobs().use(
  middleware.auth({
    guards: ['basicAuth'],
  })
);

---

Conclusion

With adonisjs-jobs and BullMQ, managing background tasks in AdonisJS becomes seamless. By following this guide, you can set up job processing, dispatch tasks efficiently, and monitor your queues with a dedicated dashboard. For more advanced configurations, explore the BullMQ documentation and AdonisJS resources.