# Node-Cron

> Job Scheduling for Node.js

Schedule tasks with cron expressions. Prevent overlaps. Coordinate across instances. Run jobs in background processes. Zero dependencies.

## Table of Contents

### Get Started

- [Quickstart](/getting-started.md): Install node-cron and run your first scheduled task in five minutes, in CommonJS and ESM, plus what actually happens when a task runs.
- [Usage Rules & Limits](/usage-rules.md): When to use node-cron and when not to. A decision matrix for schedule vs createTask vs background tasks, plus node-cron's limits as an in-process, non-durable, non-distributed scheduler.

### Core Concepts

- [Cron Syntax](/cron-syntax.md): How node-cron interprets cron expressions, covering fields, allowed values, ranges, steps, lists, named months and weekdays, plus a copy-paste table of common schedules.
- [Task Lifecycle & Status](/task-lifecycle.md): How a node-cron task moves through stopped, idle, running, and destroyed, and how to control it with start, stop, destroy, execute, getStatus, and getNextRun.
- [Scheduling Options](/scheduling-options.md): Fine-tune node-cron tasks with timezone, noOverlap, maxExecutions, maxRandomDelay, name, logger, and suppressMissedWarning, with examples for each.
- [Timezones & DST](/timezones-and-dst.md): How node-cron evaluates schedules in a timezone, exactly what it does across daylight-saving transitions (spring-forward gaps and fall-back overlaps), and how to opt out of DST entirely.

### Scaling Up

- [Events & Observability](/event-listening.md): Subscribe to node-cron task lifecycle events (task started/stopped/destroyed and execution started/finished/failed/missed/overlap/maxReached), each carrying a TaskContext.
- [Background Tasks](/background-tasks.md): Run node-cron jobs in isolated forked processes so heavy work never blocks your main event loop. Covers task files, scheduling, events, and executeTimeout.
- [Distributed Coordination](/distributed-coordination.md): Run a node-cron task on a single instance per fire across a fleet of replicas. Covers the distributed option, the NODE_CRON_RUN env-var default, custom RunCoordinators (e.g. Redis) for HA, and the execution:skipped event.
- [Logging](/logging.md): Route node-cron's internal messages through your own logger with setLogger or the per-task logger option, integrate winston/pino, silence output, and control the missed-execution warning.

### Ecosystem

- [NestJS (@node-cron/nestjs)](/nestjs.md): Use node-cron in NestJS with @node-cron/nestjs, a drop-in replacement for @nestjs/schedule. Keep the same @Cron, @Interval and @Timeout decorators and gain distributed scheduling, background tasks in a forked process, lifecycle events, jitter and DST-correct timezones that @nestjs/schedule does not have.
- [Fastify (@node-cron/fastify)](/fastify.md): Schedule jobs in Fastify with @node-cron/fastify, the official node-cron plugin. Register it like @fastify/schedule and get real cron expressions, distributed-ready scheduling, background tasks in a forked process, timezones and per-execution events.
- [Plain English to Cron (cron-translate)](/cron-translate.md): Translate plain English schedules like "every weekday at 6pm" into cron expressions for node-cron, and turn cron expressions back into readable English. Zero-dependency, TypeScript-native.
- [Cron Expression Tester](/cron-tester.md): Paste a cron expression and read it back in plain English, instantly. Powered by cron-translate, built for node-cron's 6-field format. Translate cron to English and English to cron right in your browser.

### Recipes

- [Cookbook](/cookbook.md): Practical, copy-paste node-cron recipes for daily backups, periodic cleanup, timezone-aware health checks, jitter, retry on failure, run-once jobs, and graceful shutdown.

### Common Problems

- [How to Prevent Overlapping Cron Jobs in Node.js](/prevent-overlapping-cron-jobs.md): Prevent duplicate cron executions when a task runs longer than its interval. One option, no external locking, built into node-cron.
- [How to Run Cron Jobs Across Multiple Servers in Node.js](/run-cron-jobs-across-multiple-servers.md): Prevent duplicate cron executions across replicas, pods, or instances. node-cron's distributed mode ensures one execution per scheduled fire across your fleet.
- [How to Run Background Jobs in Node.js](/run-background-jobs-in-nodejs.md): Run scheduled jobs in isolated forked processes so heavy work never blocks your main event loop. Built into node-cron, no external queue needed.

### Reference

- [API Reference](/api-reference.md): Complete reference for the node-cron module (schedule, createTask, validate, getTasks, getTask, and setLogger), with parameters, return types, and examples.
- [Migrating from v2](/migrating-from-v2.md): What changed between node-cron v2 and v3, covering the removed task.getStatus() and task.destroy() methods, the dropped boolean immediateStart argument, and the new background tasks, events, and getTasks API.
- [Migrating from v3](/migrating-from-v3.md): What changed between node-cron v3 and v4, covering the Node.js 20 and ESM requirements, the TypeScript rewrite, smarter scheduling, the streamlined Options type, createTask, the new method names, and the rebuilt event system.
- [Migrating from cron](/migrating-from-cron.md): How to move from the cron package to node-cron. The two similarly named packages compared, plus a complete API mapping for CronJob, timeZone, onComplete, runOnInit, and the task lifecycle methods.

### Other

- [Sponsors](/sponsors.md): node-cron has run in production since 2016, now in 220,000+ repositories with zero dependencies. If it helps your team, you can help keep it going.
- [Task Controls](/task-controls.md): This page has moved to Task Lifecycle & Status.