How to Use Scheduling in NestJS: Simple Guide with Examples

In NestJS, use the @nestjs/schedule package to add scheduling capabilities. Import ScheduleModule in your module, then create tasks using decorators like @Interval(), @Timeout(), or @Cron() inside injectable services.

Syntax

To use scheduling in NestJS, first import ScheduleModule in your root or feature module. Then create a service where you define scheduled tasks using decorators:

• @Interval(milliseconds): runs a method repeatedly every given milliseconds.
• @Timeout(milliseconds): runs a method once after the given milliseconds.
• @Cron(cronExpression): runs a method based on a cron schedule.

Each decorator is placed above a method inside a service class decorated with @Injectable().

typescript

import { Module } from '@nestjs/common';
import { ScheduleModule } from '@nestjs/schedule';
import { TasksService } from './tasks.service';

@Module({
  imports: [ScheduleModule.forRoot()],
  providers: [TasksService],
})
export class AppModule {}

import { Injectable } from '@nestjs/common';
import { Interval, Timeout, Cron } from '@nestjs/schedule';

@Injectable()
export class TasksService {
  @Interval(10000) // every 10 seconds
  handleInterval() {
    console.log('Interval task running');
  }

  @Timeout(5000) // once after 5 seconds
  handleTimeout() {
    console.log('Timeout task executed');
  }

  @Cron('45 * * * * *') // at second 45 every minute
  handleCron() {
    console.log('Cron task executed at 45 seconds');
  }
}

Example

This example shows a NestJS service that logs messages on different schedules: every 10 seconds, once after 5 seconds, and at the 45th second of every minute.

typescript

import { Module } from '@nestjs/common';
import { ScheduleModule } from '@nestjs/schedule';
import { Injectable } from '@nestjs/common';
import { Interval, Timeout, Cron } from '@nestjs/schedule';

@Injectable()
export class TasksService {
  @Interval(10000)
  handleInterval() {
    console.log('Interval task running');
  }

  @Timeout(5000)
  handleTimeout() {
    console.log('Timeout task executed');
  }

  @Cron('45 * * * * *')
  handleCron() {
    console.log('Cron task executed at 45 seconds');
  }
}

@Module({
  imports: [ScheduleModule.forRoot()],
  providers: [TasksService],
})
export class AppModule {}

Output

Timeout task executed
Interval task running
Interval task running
Cron task executed at 45 seconds
Interval task running
... (repeats every 10 seconds and at 45 seconds each minute)

Common Pitfalls

Common mistakes when using scheduling in NestJS include:

• Not importing ScheduleModule.forRoot() in the module, so decorators won't work.
• Forgetting to add the service with scheduled methods to the module's providers.
• Using incorrect cron expressions causing tasks not to run as expected.
• Placing decorators on non-methods or static methods, which won't be triggered.

Always ensure your scheduled methods are instance methods inside an injectable service.

typescript

/* Wrong: Missing ScheduleModule import */
@Module({
  providers: [TasksService],
})
export class AppModule {}

/* Right: Include ScheduleModule.forRoot() */
@Module({
  imports: [ScheduleModule.forRoot()],
  providers: [TasksService],
})
export class AppModule {}

Quick Reference

Decorator	Purpose	Example Usage
@Interval(milliseconds)	Run method repeatedly every given milliseconds	@Interval(10000) // every 10 seconds
@Timeout(milliseconds)	Run method once after given milliseconds	@Timeout(5000) // once after 5 seconds
@Cron(cronExpression)	Run method on cron schedule	@Cron('45 * * * * *') // at 45 seconds every minute

Key Takeaways

Always import ScheduleModule.forRoot() in your module to enable scheduling.

Use @Interval, @Timeout, and @Cron decorators on methods inside injectable services to schedule tasks.

Ensure cron expressions are correct to avoid unexpected scheduling behavior.

Scheduled methods must be instance methods, not static or outside services.

Add your scheduling service to the module's providers array.