@nestjs/schedule

@nestjs/schedule is the official NestJS module for running scheduled tasks, built on top of the cron package. It lets developers annotate provider methods with @Cron(), @Interval(), or @Timeout() decorators and have the framework register, start, and manage those jobs automatically as part of the application lifecycle.

Under the hood, a ScheduleExplorer scans providers at bootstrap for decorated methods and hands them to a SchedulerRegistry/SchedulerOrchestrator, which tracks live cron jobs, intervals, and timeouts so they can be looked up, dynamically added, or stopped at runtime via dependency injection — rather than living as free-standing timers outside the framework’s control.

What You Get

• @Cron() decorator for cron-expression-based recurring jobs, including named jobs and timezone/UTC-offset options
• @Interval() and @Timeout() decorators for simpler recurring or delayed execution
• A SchedulerRegistry service for looking up, adding, or deleting cron jobs, intervals, and timeouts at runtime
• Automatic discovery of decorated methods across all providers via ScheduleExplorer at application bootstrap
• A ScheduleModule.forRoot() entrypoint that wires scheduling into the Nest module graph
• Dynamic module support for registering jobs outside of decorators when schedules are computed at runtime

Common Use Cases

• Running periodic maintenance tasks (cache cleanup, session expiry, report generation) inside a Nest backend
• Polling external APIs or databases on a fixed interval from within a Nest service
• Firing one-off delayed jobs after application startup via @Timeout()
• Building admin tooling that lists, pauses, or reschedules cron jobs at runtime through the SchedulerRegistry

Under The Hood

Architecture — lib/schedule.module.ts exposes a ScheduleModule.forRoot() dynamic module that wires together three collaborators: ScheduleExplorer walks the Nest module/provider graph at bootstrap (via DiscoveryService/MetadataScanner) looking for methods carrying SCHEDULE_CRON_OPTIONS/interval/timeout metadata set by the decorators; SchedulerRegistry is the injectable public API for looking up and mutating jobs by name; and SchedulerOrchestrator holds the actual live CronJob/timer instances and starts/stops them in response to lifecycle hooks (OnApplicationBootstrap, OnApplicationShutdown). Tech Stack — TypeScript targeting the Nest 11.x peer dependencies (@nestjs/common/@nestjs/core), with a single runtime dependency on the cron npm package for cron-expression parsing and timezone handling; builds with tsc, lints with oxlint, and tests with vitest (migrated off Jest). Code Quality — tests/ contains integration tests that boot a real Nest TestingModule and assert jobs get registered/executed, rather than only unit-testing decorators in isolation; the schedule.messages.ts module centralizes user-facing error strings for consistency; commit history shows steady dependency bumps via Renovate alongside human-authored feature/fix commits. API Design — decorators (@Cron(CronExpression.EVERY_MINUTE), @Interval(1000), @Timeout(5000)) read as plain annotations on ordinary provider methods, so adopting scheduling requires no boilerplate beyond importing ScheduleModule.forRoot() once; the CronExpression enum spares users from memorizing raw cron syntax for common schedules, and SchedulerRegistry gives an escape hatch to imperative control when the declarative decorator model isn’t enough.