Skip to main content
The Scheduler class is the main entry point for scheduling tasks in your AdonisJS application. It provides methods to register commands and callbacks to run on a schedule.

​
Constructor

constructor(app: ApplicationService)
​
app
ApplicationService
required
The AdonisJS application service instance

​
Properties

​
Day Constants

The Scheduler class provides constants for days of the week:
  • SUNDAY = 0
  • MONDAY = 1
  • TUESDAY = 2
  • WEDNESDAY = 3
  • THURSDAY = 4
  • FRIDAY = 5
  • SATURDAY = 6

​
Methods

​
command()

Schedule a command to run on a cron schedule. 
command(
  name: string | typeof BaseCommand,
  args?: string | string[]
): ScheduleCommand
​
name
string | typeof BaseCommand
required
The command name as a string (e.g., 'mail:send') or the command class reference
​
args
string | string[]
default:"[]"
Optional arguments to pass to the command. Can be a single string or an array of strings
​
ScheduleCommand
ScheduleCommand
Returns a ScheduleCommand instance that can be chained with frequency and configuration methods
Example 
import router from '@adonisjs/core/services/router'
import scheduler from '@adonisjs/scheduler/services/main'
import SendEmailsCommand from '#commands/send_emails'

// Schedule by command name
scheduler.command('mail:send').everyMinute()

// Schedule by command class
scheduler.command(SendEmailsCommand).daily()

// Schedule with arguments
scheduler.command('db:backup', ['--force']).daily()

​
call()

Schedule a callback function to run on a cron schedule. 
call(callback: Function): ScheduleCallback
​
callback
Function
required
The callback function to execute. Can be synchronous or asynchronous
​
ScheduleCallback
ScheduleCallback
Returns a ScheduleCallback instance that can be chained with frequency and configuration methods
Example 
import scheduler from '@adonisjs/scheduler/services/main'
import mail from '@adonisjs/mail/services/main'

scheduler.call(async () => {
  await mail.send((message) => {
    message.to('admin@example.com')
    message.subject('Daily Report')
  })
}).daily()

​
withoutOverlapping()

Apply the withoutOverlapping configuration to all tasks defined within the callback. 
withoutOverlapping(
  callback: () => void,
  config?: { expiresAt: number }
): void
​
callback
() => void
required
A callback function where you define tasks. All tasks defined within this callback will have withoutOverlapping enabled
​
config
{ expiresAt: number }
default:"{ expiresAt: 3600000 }"
Configuration object with expiresAt property (in milliseconds) that determines when the lock expires
Example 
import scheduler from '@adonisjs/scheduler/services/main'

scheduler.withoutOverlapping(() => {
  scheduler.command('db:backup').daily()
  scheduler.command('reports:generate').hourly()
}, { expiresAt: 7200000 }) // 2 hours

​
withTag()

Apply a tag to all tasks defined within the callback. 
withTag(callback: () => void, tag: string): void
​
callback
() => void
required
A callback function where you define tasks. All tasks defined within this callback will have the specified tag
​
tag
string
required
The tag name to apply to all tasks within the callback
Example 
import scheduler from '@adonisjs/scheduler/services/main'

scheduler.withTag(() => {
  scheduler.command('analytics:process').everyFiveMinutes()
  scheduler.command('reports:generate').hourly()
}, 'analytics')

scheduler.withTag(() => {
  scheduler.command('emails:send').everyMinute()
  scheduler.command('notifications:dispatch').everyTwoMinutes()
}, 'communications')

​
onStarting()

Register a callback that will be executed before the scheduler starts processing tasks for a specific tag. 
onStarting(callback: ({ tag }: { tag: string }) => void | Promise<void>): void
​
callback
({ tag }: { tag: string }) => void | Promise<void>
required
A callback function that receives an object with the tag name. Can be synchronous or asynchronous
Example 
import scheduler from '@adonisjs/scheduler/services/main'
import logger from '@adonisjs/core/services/logger'

scheduler.onStarting(({ tag }) => {
  logger.info(`Scheduler starting for tag: ${tag}`)
})

​
onStarted()

Register a callback that will be executed after the scheduler has started processing tasks for a specific tag. 
onStarted(callback: ({ tag }: { tag: string }) => void | Promise<void>): void
​
callback
({ tag }: { tag: string }) => void | Promise<void>
required
A callback function that receives an object with the tag name. Can be synchronous or asynchronous
Example 
import scheduler from '@adonisjs/scheduler/services/main'
import logger from '@adonisjs/core/services/logger'

scheduler.onStarted(({ tag }) => {
  logger.info(`Scheduler started successfully for tag: ${tag}`)
})

​
onBoot()

Register a callback that will be executed when the scheduler is booting, before loading decorator-based schedules. 
onBoot(callback: () => void | Promise<void>): void
​
callback
() => void | Promise<void>
required
A callback function to execute during boot. Can be synchronous or asynchronous
Example 
import scheduler from '@adonisjs/scheduler/services/main'
import logger from '@adonisjs/core/services/logger'

scheduler.onBoot(async () => {
  logger.info('Scheduler is booting...')
  // Perform any initialization tasks
})

​
boot()

Initializes the scheduler by loading all commands and decorator-based schedules. This method is called automatically by the Worker. 
async boot(): Promise<void>
This method:
  1. Calls the onBoot callback if registered
  2. Loads commands from the application’s commands path
  3. Loads commands defined in .adonisrc.json
  4. Registers all decorator-based schedules
Note: You typically don’t need to call this method manually as it’s automatically invoked by the Worker.

Build docs developers (and LLMs) love

Get started for freeTalk to us