@robojs/cron

Easily schedule and manage recurring tasks with cron expressions.

MIT42.5 kB Package Size 7.2 kB Bundle Size

Install @robojs/cron with:

Schedule recurring tasks with cron expressions. Run functions at specific times, persist jobs across restarts, and control them dynamically — all with a simple API.

Features

Cron Scheduling

Six-field cron expressions

Simple API

One-liner job creation

File-Based Jobs

Modular job handlers

Persistence

Survive restarts with Flashcore

Job Control

Pause, resume, and stop

Pattern Presets

72+ readable schedule helpers

Installation

To add this plugin to your Robo.js project:

npx robo add @robojs/cron@next

Or create a new project with the plugin pre-installed:

npx create-robo@next my-project -p @robojs/cron@next

No configuration needed. The plugin works out of the box.

Quick start

Import Cron and pass a cron expression with a callback. The job starts immediately.

src/robo/start.ts

import { Cron } from '@robojs/cron'

export default () => {
	Cron('*/10 * * * * *', () => {
		console.log('This runs every 10 seconds')
	})
}

src/robo/start.js

import { Cron } from '@robojs/cron'

export default () => {
	Cron('*/10 * * * * *', () => {
		console.log('This runs every 10 seconds')
	})
}

The start lifecycle hook is a good place to register jobs that should run for the lifetime of your Robo.

Using patterns

Don't want to memorize cron syntax? Use the Patterns helper for readable scheduling.

src/robo/start.ts

import { Cron, Patterns } from '@robojs/cron'

export default () => {
	Cron(Patterns.EVERY_HOUR, () => {
		console.log('Hourly task')
	})

	Cron(Patterns.everyDayAt('14:30'), () => {
		console.log('Runs daily at 2:30 PM')
	})

	Cron(Patterns.everyWeekdayAt('09:00'), () => {
		console.log('Weekday morning task')
	})
}

src/robo/start.js

import { Cron, Patterns } from '@robojs/cron'

export default () => {
	Cron(Patterns.EVERY_HOUR, () => {
		console.log('Hourly task')
	})

	Cron(Patterns.everyDayAt('14:30'), () => {
		console.log('Runs daily at 2:30 PM')
	})

	Cron(Patterns.everyWeekdayAt('09:00'), () => {
		console.log('Weekday morning task')
	})
}

Patterns includes 58 preset constants, 7 day-of-week constants, and 18 builder functions. See the full Patterns reference for the complete list.

Job control

Cron returns a job instance with methods to control execution.

const job = Cron('*/10 * * * * *', () => {
	console.log('Running...')
})

// Temporarily halt the job
job.pause()

// Resume after pausing
job.resume()

// Permanently stop the job
job.stop()

// Check the next scheduled run
const nextRun = job.nextRun()
console.log('Next run:', nextRun)

const job = Cron('*/10 * * * * *', () => {
	console.log('Running...')
})

// Temporarily halt the job
job.pause()

// Resume after pausing
job.resume()

// Permanently stop the job
job.stop()

// Check the next scheduled run
const nextRun = job.nextRun()
console.log('Next run:', nextRun)

File-based jobs

Instead of inline functions, point to a file that exports a default function. File-based jobs can be persisted across restarts.

src/robo/start.ts

import { Cron } from '@robojs/cron'

export default () => {
	// Path is relative to .robo/build/
	Cron('*/5 * * * * *', 'cron/cleanup.js')
}

src/robo/start.js

import { Cron } from '@robojs/cron'

export default () => {
	// Path is relative to .robo/build/
	Cron('*/5 * * * * *', 'cron/cleanup.js')
}

The job file must export a default function. It receives the job ID as its first argument.

src/cron/cleanup.ts

export default (jobId: string) => {
	console.log(`Running job ${jobId}`)
}

src/cron/cleanup.js

export default (jobId) => {
	console.log(`Running job ${jobId}`)
}

cleanup.tsJob handler

start.tsRegisters cron jobs

Use relative paths without a leading slash. Paths like cron/cleanup.js resolve from .robo/build/. Leading slashes are stripped automatically.

Persistence

File-based jobs can be saved to survive restarts.

import { Cron } from '@robojs/cron'

const job = Cron('0 0 * * *', 'cron/daily-report.js')
await job.save('daily-report')

import { Cron } from '@robojs/cron'

const job = Cron('0 0 * * *', 'cron/daily-report.js')
await job.save('daily-report')

Retrieve or remove saved jobs at any time.

const job = Cron.get('daily-report')
console.log('Next run:', job?.nextRun())

// Full cleanup: stop execution, then remove persistence
job?.stop()
await Cron.remove('daily-report')

const job = Cron.get('daily-report')
console.log('Next run:', job?.nextRun())

// Full cleanup: stop execution, then remove persistence
job?.stop()
await Cron.remove('daily-report')

See Persistence for the full guide on saving, restoring, and managing jobs.

Next Steps

Patterns

Use readable presets and builders instead of raw cron syntax.

Persistence

Save jobs across restarts and manage them dynamically.

Cron expressions

Learn the six-field cron format and special characters.

API reference

Full reference for Cron, CronJob, and Patterns.

@robojs/cron

Cron Scheduling

Simple API

File-Based Jobs

Persistence

Job Control

Pattern Presets

Patterns

Persistence

Cron expressions

API reference

On this page