---
url: /getting-started.md
description: >-
  Install node-cron and run your first scheduled task in five minutes, in
  CommonJS and ESM, plus what actually happens when a task runs.
---

# Quickstart

`node-cron` is a lightweight task scheduler for Node.js, written in TypeScript and inspired by [GNU crontab](https://www.gnu.org/software/mcron/manual/html_node/Crontab-file.html). It runs recurring tasks on a schedule you describe with standard cron syntax, and has **zero runtime dependencies**.

This page gets you from zero to a running task in five minutes. By the end you'll have scheduled a task, seen it run, and know where to go next.

## 1. Install

```bash
npm install node-cron
```

`node-cron` ships both CommonJS and ESM builds and bundled TypeScript types, so it works out of the box in any modern Node.js project.

> Requires **Node.js 20 or newer**. Tested on Node 20, 22, and 24.

## 2. Schedule your first task

Import node-cron and schedule a function to run every minute.

::: code-group

```js [ESM]
import cron from 'node-cron';

cron.schedule('* * * * *', () => {
  console.log('Running a task every minute');
});
```

```js [CommonJS]
const cron = require('node-cron');

cron.schedule('* * * * *', () => {
  console.log('Running a task every minute');
});
```

:::

That's it. The `* * * * *` expression means "every minute". Run the file and you'll see the message print at the top of each minute.

## 3. What just happened

`cron.schedule(expression, task)` does two things:

1. **Creates** a scheduled task from your cron expression and function.
2. **Starts** it immediately, so it begins matching the clock right away.

It returns a [`ScheduledTask`](/task-lifecycle) object you can hold onto to control the task later:

```js
import cron from 'node-cron';

const task = cron.schedule('* * * * *', () => {
  console.log('tick');
});

task.stop();    // pause it
task.start();   // resume it
task.destroy(); // remove it for good
```

> 💡 Want a task that does **not** start right away? Use [`cron.createTask`](/api-reference#createtask-expression-func-options) instead of `cron.schedule`. Same arguments, but you call `.start()` yourself.

## 4. Tasks receive a context

Every task function is called with a `TaskContext` describing the run, useful for logging and metrics:

```js
import cron from 'node-cron';

cron.schedule('* * * * *', (ctx) => {
  console.log(`scheduled for: ${ctx.dateLocalIso}`);
  console.log(`started at:    ${ctx.triggeredAt.toISOString()}`);
});
```

The full `TaskContext` shape, and the events that carry it, is covered in [Events & Observability](/event-listening#taskcontext).

## Next steps

You've scheduled, run, and controlled a task. Now learn to express *exactly* when it should run:

* **[Cron Syntax](/cron-syntax)**: ranges, steps, lists, and named months/weekdays.
* [Task Lifecycle & Status](/task-lifecycle): what `start`, `stop`, and `getStatus` actually do.
* [Scheduling Options](/scheduling-options): timezones, overlap prevention, and execution limits.

---

---
url: /usage-rules.md
description: >-
  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.
---

# Usage Rules & Limits

A quick guide to picking the right tool and the right API. node-cron is an **in-process** scheduler: it runs tasks inside your Node.js process (or a forked child process for background tasks). It is small, dependency-free, and great for recurring work that lives with your app. It is **not** a durable or distributed job queue.

## Decision matrix

| Goal                                              | Use                                                                 |
| ------------------------------------------------- | ------------------------------------------------------------------- |
| Run a function on a schedule, starting now        | [`cron.schedule(expr, fn)`](/api-reference#schedule-expression-func-options) |
| Configure or attach listeners before it starts    | [`cron.createTask(...)`](/api-reference#createtask-expression-func-options) then `.start()` |
| Prevent overlapping runs                           | [`noOverlap: true`](/scheduling-options)                            |
| Run CPU-heavy, blocking, or long work              | [Background task](/background-tasks) (pass a file path)             |
| React to success, failure, or missed runs          | [`task.on('execution:*')`](/event-listening)                        |
| Run on the last day of the month                   | [`L` in the day-of-month field](/cron-syntax#last-day-of-the-month-l) |
| Run a fixed number of times                        | [`maxExecutions`](/scheduling-options)                              |
| Stagger many tasks firing at once                  | [`maxRandomDelay`](/scheduling-options)                             |
| Route internal logs through your logger            | [`setLogger` / `logger`](/logging)                                  |
| Durable, distributed, retried jobs                 | **Not node-cron.** Use [Sidequest](https://sidequestjs.com) or a queue |

## Usage rules

* Use **`cron.schedule`** when you want the task to start immediately.
* Use **`cron.createTask`** when you need to attach [event listeners](/event-listening) or inspect the task before it starts, then call `.start()`.
* Use a **[background task](/background-tasks)** (a file path instead of a function) for CPU-bound, blocking, or long-running work, so it does not block the main event loop.
* Use **`noOverlap: true`** when a run can take longer than its interval and you do not want overlapping executions.
* Attach **`execution:failed`** / **`execution:missed`** listeners to observe problems; listening to `execution:missed` also silences the default missed-execution warning.
* Set a **`timezone`** so schedules are unambiguous across environments.

## Limits: when not to use node-cron

node-cron deliberately stays small. It does **not** provide:

* **Durability.** Schedules live in memory. If the process restarts, pending runs are lost and node-cron does not "catch up" runs it missed while down.
* **Distribution or coordination.** Each process runs its own schedule independently. There is no leader election or locking, so if you run **N replicas**, a task scheduled in each one runs **N times**. Guard cluster jobs yourself (run the scheduler on a single instance, or add your own lock).
* **Persistent retries, uniqueness, priorities, or a dashboard.**

If you need any of the above (durable jobs that survive restarts, retries with backoff, exactly-once across a cluster, a monitoring UI), reach for a durable job runner such as [**Sidequest.js**](https://sidequestjs.com) or a queue backed by a datastore, rather than node-cron alone.

## Next steps

* [Quickstart](/getting-started): install and run your first task.
* [Cookbook](/cookbook): copy-paste recipes for the cases above.

---

---
url: /cron-syntax.md
description: >-
  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.
---

# Cron Syntax

A cron expression is how you tell node-cron *when* a task should run. `node-cron` uses the standard cron format with **five or six fields**, where the leading **seconds** field is optional.

```plaintext
# ┌────────────── second (optional)
# │ ┌──────────── minute
# │ │ ┌────────── hour
# │ │ │ ┌──────── day of month
# │ │ │ │ ┌────── month
# │ │ │ │ │ ┌──── day of week
# │ │ │ │ │ │
# * * * * * *
```

When you provide **five** fields, the seconds field defaults to `0` (the task runs at the start of the matched minute). Provide **six** fields to schedule down to the second.

::: tip Prefer plain English?
[`cron-translate`](/cron-translate) turns phrases like `every weekday at 6pm` into cron expressions (and back), so you can write `cron.schedule(toCron('every weekday at 6pm'), ...)` without hand-counting fields.
:::

## Allowed values per field

| Field          | Values                              |
| -------------- | ----------------------------------- |
| second         | `0-59` (optional)                   |
| minute         | `0-59`                              |
| hour           | `0-23`                              |
| day of month   | `1-31` (or [`L`](#last-day-of-the-month-l), [`L-n`](#n-days-before-the-last-day-l-n), [`15W`/`LW`](#nearest-weekday-w), [`?`](#no-specific-value)) |
| month          | `1-12` (or names, e.g. `Jan`, `Sep`)|
| day of week    | `0-7` (or names; `0` and `7` are Sunday; [`2#3`](#nth-weekday), [`5L`](#last-weekday-of-the-month-weekdayl), [`?`](#no-specific-value)) |

Each field also accepts `*` (any value), ranges, steps, and comma-separated lists, described below. The whole expression can also be a [nickname](#nicknames-daily-hourly) like `@daily`.

## Common schedules

Copy-paste reference for the expressions you'll reach for most often:

| Expression       | Runs                                  |
| ---------------- | ------------------------------------- |
| `* * * * *`      | Every minute                          |
| `*/5 * * * *`    | Every 5 minutes                       |
| `0 * * * *`      | Every hour, on the hour               |
| `0 0 * * *`      | Every day at midnight                 |
| `0 3 * * *`      | Every day at 03:00                    |
| `0 9 * * 1-5`    | At 09:00, Monday through Friday       |
| `0 0 1 * *`      | At midnight on the 1st of each month  |
| `0 0 L * *`      | At midnight on the last day of each month |
| `0 0 * * 0`      | At midnight every Sunday              |
| `0 0 12 * * 1#1` | At 12:00 on the first Monday of every month |
| `0 0 18 * * 5L`  | At 18:00 on the last Friday of every month  |
| `0 0 15W * *`    | At midnight on the weekday nearest the 15th |
| `0 0 L-3 * *`    | At midnight 3 days before the end of the month |
| `*/30 * * * * *` | Every 30 seconds (6-field form)       |
| `@daily`         | Every day at midnight (nickname)      |

## Building expressions

### Lists: multiple specific values

Use commas to run a task at several specific values in a field.

```js
import cron from 'node-cron';

// Runs at minutes 1, 2, 4, and 5 of every hour
cron.schedule('1,2,4,5 * * * *', () => {
  console.log('Running at minutes 1, 2, 4, and 5 of each hour');
});
```

> This expression has five fields, so the **seconds** field is omitted and defaults to `0`.

### Ranges: a continuous interval

Use a dash (`-`) to define an inclusive range.

```js
import cron from 'node-cron';

// Runs every minute from minute 1 to minute 5 (inclusive) of every hour
cron.schedule('1-5 * * * *', () => {
  console.log('Running every minute from 1 to 5');
});
```

This is equivalent to `1,2,3,4,5`, a cleaner way to express consecutive values.

### Steps: periodic intervals

Use a slash (`/`) after a wildcard or range to define a step.

```js
import cron from 'node-cron';

// Every 2 minutes (even minutes: 0, 2, 4, ...)
cron.schedule('*/2 * * * *', () => {
  console.log('Running every 2 minutes (even minutes)');
});

// Every 2 minutes starting from 1 (odd minutes: 1, 3, 5, ...)
cron.schedule('1-59/2 * * * *', () => {
  console.log('Running every 2 minutes starting from 1 (odd minutes)');
});
```

* `*/2` means "every 2 units" across the field's full range (`0-59` for minutes), covering all even minutes.
* `1-59/2` means "every 2 units starting from 1", covering all odd minutes.

### Names: months and weekdays

For readability, use full or abbreviated names instead of numbers for months and days of the week.

```js
import cron from 'node-cron';

// Every minute on Sundays in January and September
cron.schedule('* * * January,September Sunday', () => {
  console.log('Running on Sundays in January and September');
});

// Same schedule using short names
cron.schedule('* * * Jan,Sep Sun', () => {
  console.log('Running on Sundays in Jan and Sep');
});
```

### Last day of the month: `L`

In the **day of month** field, `L` (or lowercase `l`) means the last calendar day of the month. node-cron resolves it per month, so it lands on the 28th, 29th, 30th, or 31st as appropriate, including leap years.

```js
import cron from 'node-cron';

// Runs at 12:00 on the last day of every month
cron.schedule('0 0 12 L * *', () => {
  console.log('Running on the last day of the month');
});
```

You can combine `L` with explicit days in a list:

```js
import cron from 'node-cron';

// Runs at midnight on the 15th and on the last day of every month
cron.schedule('0 0 15,L * *', () => {
  console.log('Running on the 15th and the last day');
});
```

> Bare `L` is valid **only** in the day of month field. In the day of week field, use the `<weekday>L` form described below.

### `n` days before the last day: `L-n` {#n-days-before-the-last-day-l-n}

In the **day of month** field, `L-n` means the day `n` days *before* the last day of the month. `L-1` is the second-to-last day, `L-3` the fourth-to-last, and so on. node-cron resolves it per month, so it tracks the varying month length.

```js
import cron from 'node-cron';

// Runs at midnight 3 days before the end of every month
cron.schedule('0 0 L-3 * *', () => {
  console.log('Three days before month end');
});
```

> If the offset reaches past the start of a month (e.g. `L-29` in February), no day matches that month.

### Nearest weekday: `W` {#nearest-weekday-w}

In the **day of month** field, `nW` matches the nearest weekday (Monday to Friday) to day `n`, without crossing into an adjacent month: a Saturday shifts back to Friday, a Sunday forward to Monday, and the adjustment reverses at a month boundary rather than leaving the month. Use `LW` for the last weekday of the month. Weekends are the only adjustment; there is no holiday awareness.

```js
import cron from 'node-cron';

// Runs at midnight on the weekday nearest the 15th
cron.schedule('0 0 15W * *', () => {
  console.log('Nearest weekday to the 15th');
});

// Runs at midnight on the last weekday of every month
cron.schedule('0 0 LW * *', () => {
  console.log('Last weekday of the month');
});
```

> `W` suffixes a single day number or `L`. It cannot be used in a range or step (`1-15W`, `15W/2` are rejected).

### Nth weekday: `#` {#nth-weekday}

In the **day of week** field, `<weekday>#<nth>` matches the nth occurrence of that weekday in the month. The weekday is `0-7` (Sunday through Saturday, where `0` and `7` are both Sunday), and the occurrence is `1-5`.

```js
import cron from 'node-cron';

// Runs at 12:00 on the first Monday of every month
cron.schedule('0 12 * * 1#1', () => {
  console.log('First Monday of the month');
});

// Runs at 09:00 on the 3rd Tuesday of every month
cron.schedule('0 9 * * 2#3', () => {
  console.log('Third Tuesday of the month');
});
```

If the nth occurrence does not exist in a given month (e.g. `0#5` in a month with only four Sundays), that month is simply skipped.

### Last weekday of the month: `<weekday>L` {#last-weekday-of-the-month-weekdayl}

In the **day of week** field, `<weekday>L` matches the last occurrence of that weekday in the month.

```js
import cron from 'node-cron';

// Runs at 18:00 on the last Friday of every month
cron.schedule('0 18 * * 5L', () => {
  console.log('Last Friday of the month');
});

// Runs at midnight on the last Sunday of every month
cron.schedule('0 0 * * 0L', () => {
  console.log('Last Sunday of the month');
});
```

> Invalid forms like `8#1`, `2#6`, `2#0`, `8L`, `L5`, or bare `L` in the weekday field are rejected by [`validate`](#validating-expressions).

### No specific value: `?` {#no-specific-value}

`?` is a Quartz-style alias for `*` (any value), accepted **only** in the day-of-month and day-of-week fields. It reads as "no specific value here", a convention some schedulers require when you constrain one of the two day fields and want to leave the other unconstrained. In node-cron it behaves exactly like `*`.

```js
import cron from 'node-cron';

// Every day at 12:00, day-of-week left unconstrained
cron.schedule('0 0 12 * * ?', () => {
  console.log('Noon, any weekday');
});
```

> `?` is rejected outside the two day fields, and cannot appear in a list (`1,?`).

## Nicknames: `@daily`, `@hourly`, … {#nicknames-daily-hourly}

Instead of a full expression you can pass a nickname. node-cron expands it to the equivalent expression before scheduling, so [`validate`](#validating-expressions) accepts them too.

| Nickname                 | Equivalent    | Runs                               |
| ------------------------ | ------------- | ---------------------------------- |
| `@yearly` / `@annually`  | `0 0 1 1 *`   | Once a year, at midnight on Jan 1  |
| `@monthly`               | `0 0 1 * *`   | Once a month, at midnight on the 1st |
| `@weekly`                | `0 0 * * 0`   | Once a week, at midnight on Sunday |
| `@daily` / `@midnight`   | `0 0 * * *`   | Once a day, at midnight            |
| `@hourly`                | `0 * * * *`   | Once an hour, on the hour          |

```js
import cron from 'node-cron';

cron.schedule('@daily', () => {
  console.log('Runs every day at midnight');
});
```

> Nicknames are case-insensitive. There is no `@reboot` nickname, node-cron has no concept of process start as a schedule; use `task.execute()` for an immediate run.

## Validating expressions

Not sure an expression is valid? Check it before scheduling:

```js
import cron from 'node-cron';

cron.validate('0 12 * * *'); // true
cron.validate('not a cron'); // false
```

For tooling and richer error messages, two more helpers go beyond a boolean:

* [`validateDetailed(expr)`](/api-reference#validatedetailed-expression) returns **every** problem (which field, value, and why) without throwing.
* [`parse(expr)`](/api-reference#parse-expression) returns the decomposed fields, or throws on the first invalid one.

```js
import { validateDetailed } from 'node-cron';

validateDetailed('99 12 * * 9').errors;
// [ { field: 'minute', value: '99', ... }, { field: 'dayOfWeek', value: '9', ... } ]
```

See [`validate`](/api-reference#validate-expression), [`validateDetailed`](/api-reference#validatedetailed-expression), and [`parse`](/api-reference#parse-expression) in the API reference.

## Next steps

Now that you can describe *when* a task runs, learn how to manage it once it's running:

* **[Task Lifecycle & Status](/task-lifecycle)**: start, stop, inspect, and destroy tasks.
* [Scheduling Options](/scheduling-options): timezones, overlap prevention, and limits.

---

---
url: /task-lifecycle.md
description: >-
  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.
---

# Task Lifecycle & Status

Both `cron.schedule` and `cron.createTask` return a `ScheduledTask`: a single, consistent interface for controlling and inspecting a task, whether it runs inline (in your process) or as a [background task](/background-tasks) (in a forked process).

This page explains the states a task moves through and the methods you use to drive it.

## The lifecycle states

Every task is always in exactly one of four states:

| Status        | Meaning                                                        |
| ------------- | -------------------------------------------------------------- |
| `stopped`     | Scheduler is not running. The task will not fire.              |
| `idle`        | Scheduler is running and waiting for the next match.           |
| `running`     | The task function is currently executing.                      |
| `destroyed`   | The task is permanently removed and cannot be restarted.       |

They transition like this:

```
          start()              (match fires)
stopped ──────────▶ idle ──────────────────▶ running
   ▲                 │  ◀──────────────────────┘
   │                 │      (execution ends)
   └─────────────────┘
        stop()

   any state ──── destroy() ────▶ destroyed   (terminal)
```

* `cron.schedule(...)` returns a task already in **`idle`** (it auto-starts).
* `cron.createTask(...)` returns a task in **`stopped`** until you call `.start()`.
* Once **`destroyed`**, a task is gone; only `getStatus()` remains meaningful.

Read the current state at any time with [`getStatus()`](#getstatus).

## Inline vs. background: sync vs. async

The control methods share one interface but differ in return type:

* **Inline tasks** (a function) act **synchronously**: `start()`, `stop()`, and `destroy()` return `void`.
* **Background tasks** (a file path) cross a process boundary, so the same methods return a **`Promise`** you should `await`.

The interface reflects this with `void | Promise<void>`, so writing `await task.stop()` is safe for both; it just resolves immediately for inline tasks.

```js
import cron from 'node-cron';

// Inline: synchronous
const task = cron.schedule('* * * * *', () => {});
task.getStatus(); // 'idle'
task.stop();
task.getStatus(); // 'stopped'

// Background: asynchronous
const bg = cron.schedule('* * * * *', './tasks/job.js');
await bg.stop();          // wait for the forked process to terminate
bg.getStatus();           // 'stopped'
```

## The ScheduledTask interface

```ts
export interface ScheduledTask {
  id: string;
  name?: string;

  start(): void | Promise<void>;
  stop(): void | Promise<void>;
  destroy(): void | Promise<void>;
  execute(): Promise<any>;
  getStatus(): string;
  getNextRun(): Date | null;

  // Inspection
  getNextRuns(count: number): Date[];
  match(date: Date): boolean;
  msToNext(): number | null;
  isBusy(): boolean;
  runsLeft(): number | undefined;
  getPattern(): string;
  lastRun(): LastRun | null;

  unref(): void;
  ref(): void;

  on(event: TaskEvent, fn: (context: TaskContext) => void | Promise<void>): void;
  off(event: TaskEvent, fn: (context: TaskContext) => void | Promise<void>): void;
  once(event: TaskEvent, fn: (context: TaskContext) => void | Promise<void>): void;
}
```

The `on`, `off`, and `once` methods are covered in [Events & Observability](/event-listening).

## Methods

### `start()`

Starts the scheduler, moving the task from `stopped` to `idle`.

* **Inline tasks:** begins evaluating the cron expression and runs the function at matched times.
* **Background tasks:** forks a dedicated process and starts a daemon that handles scheduling.
* Has no effect if the task is already running.

### `stop()`

Stops the scheduler and prevents future runs, moving the task to `stopped`.

* **Inline tasks:** halts scheduling, but a run already in progress is allowed to finish.
* **Background tasks:** terminates the child process.
* This does **not** remove the task; use [`destroy()`](#destroy) for that. A stopped task can be started again.

### `destroy()`

Permanently deactivates the task and releases its resources, moving it to `destroyed`.

* **Background tasks:** kills the associated process and detaches listeners.
* After destruction, don't call any method other than `getStatus()`.
* The task is also removed from the module registry (so it no longer appears in [`getTasks()`](/api-reference#gettasks)).

### `execute()`

Runs the task function **immediately**, outside its schedule. Always returns a `Promise`.

```js
import cron from 'node-cron';

const task = cron.schedule('0 3 * * *', async () => {
  return doBackup();
});

// Trigger a run right now without waiting for 03:00
const result = await task.execute();
```

* Useful for testing, debugging, or ad-hoc runs.
* Resolves with the task's return value, or rejects if it throws.
* Emits the same lifecycle events as a scheduled run, with `execution.reason === 'invoked'`.

### `getStatus()`

Returns the current state as a string: `'stopped'`, `'idle'`, `'running'`, or `'destroyed'`. Synchronous for both task types.

```js
import cron from 'node-cron';

const task = cron.schedule('* * * * *', () => {});
console.log(task.getStatus()); // 'idle'
```

### `getNextRun()`

Returns the next scheduled run time as a `Date`, or `null` if the task is stopped, destroyed, or its expression yields no future match.

```js
import cron from 'node-cron';

const task = cron.schedule('0 * * * *', () => {});
console.log(task.getNextRun()); // e.g. 2026-06-16T15:00:00.000Z
```

## Inspecting a task

Beyond status and the next run, a task exposes a few read-only methods for previewing its schedule and seeing what it's doing right now, handy for dashboards, health checks, and tests. They work the same for inline and background tasks.

### `getNextRuns(count)`

Returns the next `count` run times as an array of `Date`s, strictly increasing. Useful for previewing a schedule ("when will this fire next?") without waiting.

```js
import cron from 'node-cron';

const task = cron.schedule('0 0 12 * * *', () => {});
task.getNextRuns(3);
// [ 2026-06-18T12:00:00.000Z, 2026-06-19T12:00:00.000Z, 2026-06-20T12:00:00.000Z ]
```

A non-positive `count` returns an empty array. Unlike [`getNextRun()`](#getnextrun), this works regardless of the task's state (it computes from the expression).

### `match(date)`

Returns `true` if the given `Date` matches the task's cron expression (evaluated in the task's timezone).

```js
const task = cron.schedule('0 0 12 * * *', () => {}, { timezone: 'Etc/UTC' });
task.match(new Date('2026-06-18T12:00:00Z')); // true
task.match(new Date('2026-06-18T12:00:01Z')); // false
```

### `msToNext()`

Milliseconds from now until the next run, or `null` when the task is stopped.

```js
const task = cron.schedule('0 * * * *', () => {});
task.msToNext(); // e.g. 1830000
```

### `isBusy()`

`true` while an execution is in progress (the task is in the `running` state), `false` otherwise. Useful before triggering work or shutting down.

```js
if (!task.isBusy()) await task.execute();
```

### `runsLeft()`

When [`maxExecutions`](/scheduling-options) is set, the number of runs remaining before the task destroys itself; otherwise `undefined`.

```js
const task = cron.schedule('* * * * * *', () => {}, { maxExecutions: 3 });
task.runsLeft(); // 3, then 2, 1, 0
```

### `getPattern()`

Returns the original cron expression the task was created with.

```js
const task = cron.schedule('0 0 12 * * *', () => {});
task.getPattern(); // '0 0 12 * * *'
```

### `lastRun()`

Returns information about the last actual execution, or `null` if the task has not run yet.

```js
const task = cron.schedule('* * * * *', async () => {
  return fetchData();
});

// Before any execution
task.lastRun(); // null

// After a successful run
task.lastRun(); // { date: Date, result: ... }

// After a failed run
task.lastRun(); // { date: Date, error: Error }
```

The `date` reflects when the execution actually ran (finish time), not when the scheduler tick was checked. The return type is:

```ts
type LastRun = { date: Date; result?: unknown; error?: Error };
```

`LastRun` is exported from the package for TypeScript users.

## Keeping the process alive: `unref()` / `ref()` {#unref-ref}

By default a running task keeps an active timer, which keeps the Node.js process alive. In a long-running server that's what you want. In a short-lived CLI or script, it can stop the process from exiting once the real work is done.

`task.unref()` [unref](https://nodejs.org/api/timers.html#timeoutunref)'s the task's internal timer, so the task keeps firing as long as *something else* keeps the process up, but no longer holds it open on its own. `task.ref()` reverses it.

```js
import cron from 'node-cron';

const task = cron.schedule('* * * * * *', () => heartbeat());
task.unref(); // this task alone won't keep the process running
```

To start a task in the unref'd state without a separate call, pass the [`unref`](/scheduling-options) option to `schedule`/`createTask`.

> Applies to inline tasks. Background tasks run in a forked process and don't hold the parent's event loop open through this timer.

## Creating a stopped task

When you need a task that doesn't start immediately (to attach listeners first, start it conditionally, or control timing in tests), use `cron.createTask` and start it yourself:

```js
import cron from 'node-cron';

const task = cron.createTask('* * * * *', () => {
  console.log('manually started');
});

task.getStatus(); // 'stopped'
task.start();
task.getStatus(); // 'idle'
```

## Next steps

* **[Scheduling Options](/scheduling-options)**: fine-tune behavior with timezones, overlap prevention, and limits.
* [Events & Observability](/event-listening): react to the lifecycle transitions described here.

---

---
url: /scheduling-options.md
description: >-
  Fine-tune node-cron tasks with timezone, noOverlap, maxExecutions,
  maxRandomDelay, name, logger, and suppressMissedWarning, with examples for
  each.
---

# Scheduling Options

A bare `cron.schedule(expression, task)` already covers the common case. As your jobs grow more demanding, the optional third argument lets you tune *how* they run, without changing the rest of your code.

```js
cron.schedule(expression, task, options);
```

## All options

```ts
export type Options = {
  name?: string;
  timezone?: string;
  noOverlap?: boolean;
  maxExecutions?: number;
  maxRandomDelay?: number;
  logger?: Logger;
  suppressMissedWarning?: boolean;
  missedExecutionTolerance?: number;
  distributed?: boolean;             // run on one instance per fire across a fleet
  runCoordinator?: RunCoordinator;   // per-task coordinator (overrides the global one)
  distributedLease?: number;           // lease ms for lease-based coordinators (default 30000)
  unref?: boolean;                     // don't keep the process alive for this task's timer
  executeTimeout?: number; // background tasks only
  startTimeout?: number;   // background tasks only
};
```

| Option                  | Type      | Default | Description                                                                 |
| ----------------------- | --------- | ------- | --------------------------------------------------------------------------- |
| `name`                  | `string`  | task id | A human-readable identifier for the task. Useful for logging, debugging, and dashboards. |
| `timezone`              | `string`  | system  | The timezone the cron expression is evaluated in. Any IANA name recognized by `Intl.DateTimeFormat` (e.g. `"America/Sao_Paulo"`, `"UTC"`, `"Europe/London"`). See [Timezones & DST](/timezones-and-dst) for behavior across daylight-saving transitions. |
| `noOverlap`             | `boolean` | `false` | If `true`, a scheduled run is **skipped** when the previous run is still executing, preventing overlapping executions. |
| `maxExecutions`         | `number`  | none    | Maximum number of times the task may run. After the limit, the task is automatically destroyed. |
| `maxRandomDelay`        | `number`  | `0`     | Adds up to this many milliseconds of random delay (jitter) before each run. Spreads out tasks that would otherwise fire simultaneously. |
| `logger`                | `Logger`  | global  | A custom [logger](/logging) for this task, overriding the global one. **Not supported for [background tasks](/background-tasks).** |
| `suppressMissedWarning` | `boolean` | `false` | Silences the "missed execution" warning for this task. See [Logging](/logging#suppressing-the-missed-execution-warning). |
| `missedExecutionTolerance` | `number` | `1000` | How late (in ms) a scheduled run may wake and still execute instead of being reported as missed. Long timers drift (OS sleep, GC, throttling, clock skew), which can otherwise skip daily/weekly runs. Always capped to the gap to the next run, so it can never run a slot twice. |
| `distributed`           | `boolean` | `false` | Run this task on a **single instance per fire** across a fleet. Requires a `name`. Uses the `NODE_CRON_RUN` env-var default (one designated runner) unless a coordinator is set. See [Distributed Coordination](/distributed-coordination). |
| `runCoordinator`        | `RunCoordinator` | global | A per-task [run coordinator](/distributed-coordination#high-availability-a-custom-run-coordinator), overriding the one set with `setRunCoordinator`. Only used when `distributed` is `true`. |
| `distributedLease`        | `number`  | `30000` | Lease expiry (ms) passed to lease-based coordinators (e.g. a Redis lock) in case the holder crashes mid-run. Must exceed the run time (and, when combined with `maxRandomDelay`, the jitter too, the lease is taken before the jitter). See [Distributed Coordination](/distributed-coordination#distributedlease). Ignored by the env-var default. |
| `unref`                 | `boolean` | `false` | If `true`, the task's internal timer is [`unref`](https://nodejs.org/api/timers.html#timeoutunref)'d so it won't keep the Node.js process alive on its own. Handy for CLI tools and scripts that should exit once their real work is done. Toggle at runtime with [`task.unref()` / `task.ref()`](/task-lifecycle#unref-ref). |

> 🛈 There is no `scheduled` or `runOnInit` option anymore. Tasks created with `cron.schedule` start immediately; for a task that starts stopped, use [`cron.createTask`](/task-lifecycle#creating-a-stopped-task). To run a task immediately on demand, call [`task.execute()`](/task-lifecycle#execute). See [Migrating from v3](/migrating-from-v3).

## Examples

### Default options

```js
import cron from 'node-cron';

const task = cron.schedule('* * * * *', () => {
  console.log('Running every minute');
});
```

Runs immediately on creation, in the system timezone, with overlapping runs allowed and no execution limit.

### Custom timezone

Evaluate the expression in a specific timezone, regardless of where the server runs:

```js
import cron from 'node-cron';

const task = cron.schedule('0 0 * * *', () => {
  console.log('Midnight in São Paulo');
}, {
  timezone: 'America/Sao_Paulo',
});
```

### Prevent overlapping runs

If a task can take longer than its interval, `noOverlap` skips a run rather than starting it on top of the previous one:

```js
import cron from 'node-cron';

const task = cron.schedule('* * * * *', async () => {
  await slowJob(); // may take longer than a minute
}, {
  noOverlap: true,
});
```

A skipped run emits an [`execution:overlap`](/event-listening) event.

### Limit the number of runs

The task destroys itself after the limit is reached:

```js
import cron from 'node-cron';

const task = cron.schedule('* * * * *', () => {
  console.log('This runs 5 times, then the task is destroyed');
}, {
  maxExecutions: 5,
});
```

Reaching the limit emits [`execution:maxReached`](/event-listening). For a one-shot task, set `maxExecutions: 1`.

### Add jitter to avoid a thundering herd

When many instances schedule the same job at the same instant (e.g. across a fleet), `maxRandomDelay` staggers them:

```js
import cron from 'node-cron';

const task = cron.schedule('0 * * * *', () => {
  refreshCache();
}, {
  maxRandomDelay: 30_000, // up to 30s of random delay per run
});
```

### Run on one instance across a fleet

When several copies of your app run the same schedule, `distributed` makes a task fire on only one instance per scheduled time. Out of the box you designate the runner with the `NODE_CRON_RUN` env var; for high availability, register a [run coordinator](/distributed-coordination#high-availability-a-custom-run-coordinator) (e.g. Redis):

```js
import cron from 'node-cron';

cron.schedule('0 3 * * *', runNightlyBackup, {
  name: 'nightly-backup', // required: forms the coordination key
  distributed: true,
});
```

A not-elected instance emits [`execution:skipped`](/event-listening) instead of running. See [Distributed Coordination](/distributed-coordination) for the full picture.

### Name a task

A `name` makes logs and dashboards readable, and is exposed as `task.name`:

```js
import cron from 'node-cron';

const task = cron.schedule('0 3 * * *', () => {}, {
  name: 'nightly-backup',
});

console.log(task.name); // 'nightly-backup'
```

### Tolerate late executions

A heartbeat is armed to fire at the scheduled time, but long timers drift (OS sleep, GC, CPU throttling, clock skew), so the callback can wake a little late. By default a run that wakes within `missedExecutionTolerance` (1000ms) still executes; later than that, it is reported as [missed](/event-listening). On an underpowered host, or a daily/weekly job that can wake several seconds late, raise it:

```js
import cron from 'node-cron';

const task = cron.schedule('0 3 * * 0', runWeeklyBackup, {
  missedExecutionTolerance: 5 * 60_000, // still run if we wake up to 5 min late
});
```

The tolerance is always capped to the gap until the next run, so it can never run the same slot twice. A late run fires once and the next slot is scheduled normally.

> 🛈 **Background tasks** accept two extra options, `executeTimeout` and `startTimeout`, covered in [Background Tasks](/background-tasks#manual-execution-and-executetimeout).

## Next steps

* **[Events & Observability](/event-listening)**: hook into overlap, missed runs, failures, and more.
* [Logging](/logging): route node-cron's output through your own logger.

---

---
url: /timezones-and-dst.md
description: >-
  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.
---

# Timezones & DST

A cron expression describes a **wall-clock** time. `30 2 * * *` means "02:30 on
the clock of the task's timezone", not a fixed UTC instant. The hard part is
daylight-saving time (DST), when the local clock jumps forward or back. This
page explains exactly what node-cron does, so you can predict every run.

By default a task runs in the **system timezone**. Set [`timezone`](/scheduling-options)
to pin it to a specific zone:

```js
cron.schedule('30 2 * * *', task, { timezone: 'America/New_York' });
```

## The guarantees

Whatever the timezone and whatever DST does, node-cron holds these invariants:

1. **Wall-clock first.** The expression is matched against the local time of the
   task's timezone.
2. **Never in the past.** The next run is always strictly after the current
   instant.
3. **Never twice for the same instant.** Even when the local clock repeats an
   hour, each absolute instant fires at most once.
4. **Always moves forward.** Successive runs are strictly increasing in absolute
   time, never going backwards when the local clock does.

## Spring-forward (the gap)

When the clock springs forward (e.g. `02:00 → 03:00`), the times inside the gap
**don't exist**. node-cron **skips** them rather than guessing an adjacent time.

* A daily time that lands in the gap is skipped **for that day**. `30 2 * * *` in
  `America/New_York` has no `02:30` on the spring-forward day, so that day is
  skipped and the next run is the following day at `02:30`.
* A sub-daily expression resumes at the first valid time after the gap.
  `*/15 * * * *` goes `… 01:45, 03:00, 03:15 …` — `02:00`–`02:45` never fire.

The reasoning: you configured `02:30` on purpose. Firing at `03:00` instead
would be surprising; skipping is predictable.

## Fall-back (the overlap)

When the clock falls back (e.g. `02:00 → 01:00`), the times inside the overlap
exist **twice**. node-cron fires on the **first** occurrence and ignores the
second.

* `30 1 * * *` in `America/New_York` fires once, at `01:30` in the
  pre-transition offset (EDT). The second `01:30` (EST) is ignored that day.
* Sub-hourly expressions keep advancing monotonically in absolute time:
  after `01:59` (first pass) the next run is `02:00`, not `01:00` again. The
  local clock rewinds, the timestamps don't.

Consecutive runs are always at least the expression's interval apart (1s for
`* * * * * *`, 1 min for `* * * * *`) — never milliseconds, even during the
overlap.

## Unusual offsets

node-cron handles non-hour transitions and offsets, not just the 60-minute US
case:

* **30-minute DST** (e.g. `Australia/Lord_Howe`, `02:00 → 02:30`) — the gap and
  overlap are 30 minutes wide and handled correctly.
* **45-minute base offset** (e.g. `Pacific/Chatham`, UTC+12:45) — schedules stay
  correct with no drift.
* **Midnight transitions** (e.g. `America/Havana`, DST starts at `00:00`) — a
  `00:30` daily is skipped on the gap day, like any other gap time.

## Zones without DST

Zones like `Asia/Tokyo`, `Etc/UTC`, or `Africa/Nairobi` have no transitions, so
there are no gaps or overlaps — the schedule simply runs every day. node-cron
applies no "corrections" to them.

## The system timezone doesn't leak in

A task with an explicit `timezone` runs at the same instants no matter what the
host's `TZ` is. A task set to `America/New_York` behaves identically whether the
server is in São Paulo, Tokyo, or UTC. Only tasks **without** a `timezone` use
the system zone.

## Avoiding DST entirely

If you never want DST to affect a schedule, run it in a **fixed-offset** zone
instead of a region that observes DST.

```js
// UTC: the simplest DST-free choice
cron.schedule('0 3 * * *', task, { timezone: 'Etc/UTC' });

// A fixed offset that never shifts, e.g. always UTC-3
cron.schedule('0 3 * * *', task, { timezone: 'Etc/GMT+3' });
```

::: warning `Etc/GMT` signs are inverted
In the `Etc/GMT±N` zones the sign is **reversed** from what you'd expect (a
POSIX quirk): `Etc/GMT+3` is **UTC-3**, and `Etc/GMT-5` is **UTC+5**. When in
doubt, prefer `Etc/UTC` or a real IANA name.
:::

Use a DST-observing zone (like `America/New_York`) when you want "the same local
clock time year-round"; use a fixed-offset zone when you want "the same absolute
spacing year-round".

---

---
url: /event-listening.md
description: >-
  Subscribe to node-cron task lifecycle events (task started/stopped/destroyed
  and execution started/finished/failed/missed/overlap/maxReached), each
  carrying a TaskContext.
---

# Events & Observability

Once a task is running, you'll often want to *know* what it's doing: when it ran, whether it succeeded, how long it took, whether a run was missed. node-cron exposes this through lifecycle events.

Every `ScheduledTask`, whether inline or [background](/background-tasks), supports `.on()`, `.once()`, and `.off()`. Each listener receives a `TaskContext` with metadata about the task and the specific execution.

```js
import cron from 'node-cron';

const task = cron.schedule('* * * * *', async () => {
  return doWork();
});

task.on('execution:finished', (ctx) => {
  console.log(`done in ${ctx.execution?.finishedAt - ctx.execution?.startedAt}ms`);
});

task.on('execution:failed', (ctx) => {
  console.error('failed:', ctx.execution?.error?.message);
});
```

> 💡 Attach listeners **before** the task starts to avoid missing early events. With `cron.schedule` the task starts immediately, so for guaranteed coverage create it stopped with [`cron.createTask`](/task-lifecycle#creating-a-stopped-task), attach listeners, then call `.start()`.

## Available events

| Event                  | Payload       | Emitted when…                                                    |
| ---------------------- | ------------- | ---------------------------------------------------------------- |
| `task:started`         | `TaskContext` | The task is started via `.start()`.                              |
| `task:stopped`         | `TaskContext` | The task is stopped via `.stop()`.                               |
| `task:destroyed`       | `TaskContext` | The task is destroyed via `.destroy()`.                          |
| `task:failed`          | `TaskContext` | A [background task](/background-tasks)'s daemon exited unexpectedly (crash, OOM-kill). `ctx.error` carries the reason. Inline tasks never emit this. |
| `execution:started`    | `TaskContext` | Right before the task function runs.                             |
| `execution:finished`   | `TaskContext` | The task function finishes successfully.                         |
| `execution:failed`     | `TaskContext` | The task function throws or rejects.                             |
| `execution:missed`     | `TaskContext` | A scheduled run was missed (blocking I/O or high CPU).           |
| `execution:overlap`    | `TaskContext` | A run was skipped because a previous one was still going (`noOverlap`). |
| `execution:maxReached` | `TaskContext` | `maxExecutions` was reached. The task is then destroyed.         |
| `execution:skipped`    | `TaskContext` | A [`distributed`](/distributed-coordination) run was skipped on this instance. `ctx.reason` is `'not-elected'` (another instance ran it) or `'coordinator-error'` (the coordinator failed; failed closed). |

## Subscribing

```js
import cron from 'node-cron';

const task = cron.createTask('* * * * *', async (ctx) => {
  console.log('running at', ctx.dateLocalIso);
  return 'done';
});

// React every time
task.on('execution:finished', (ctx) => {
  console.log('result:', ctx.execution?.result);
});

// React just once, then auto-remove
task.once('task:started', () => console.log('scheduler is up'));

// Stop listening
const onFail = (ctx) => console.error(ctx.execution?.error);
task.on('execution:failed', onFail);
task.off('execution:failed', onFail);

task.start();
```

## TaskContext

Every event delivers a `TaskContext`, giving consistent access to timing and execution metadata.

```ts
export type TaskContext = {
  date: Date;
  dateLocalIso: string;
  triggeredAt: Date;
  task?: ScheduledTask;
  execution?: Execution;
  reason?: 'not-elected' | 'coordinator-error';
  error?: Error;
};
```

| Field          | Type             | Description                                                           |
| -------------- | ---------------- | --------------------------------------------------------------------- |
| `date`         | `Date`           | The time the run was scheduled for.                                   |
| `dateLocalIso` | `string`         | Human-readable local timestamp, using the task's timezone.            |
| `triggeredAt`  | `Date`           | When the event was actually emitted. Useful for spotting drift.       |
| `task`         | `ScheduledTask?` | The task instance.                                                    |
| `execution`    | `Execution?`     | Details of the run (present for `execution:*` events).                |
| `reason`       | `string?`        | Why a run was skipped. Present only on [`execution:skipped`](/distributed-coordination#knowing-when-an-instance-skips): `'not-elected'` or `'coordinator-error'`. |
| `error`        | `Error?`         | The daemon's exit error. Present only on `task:failed`.               |

### Execution

`TaskContext.execution` describes a single run of the task:

```ts
export type Execution = {
  id: string;
  reason: 'invoked' | 'scheduled';
  startedAt?: Date;
  finishedAt?: Date;
  error?: Error;
  result?: any;
};
```

| Field        | Type      | Description                                                        |
| ------------ | --------- | ----------------------------------------------------------------- |
| `id`         | `string`  | Unique id for this execution.                                     |
| `reason`     | `string`  | `'scheduled'` (fired by the schedule) or `'invoked'` (via `execute()`). |
| `startedAt`  | `Date?`   | When the run started.                                             |
| `finishedAt` | `Date?`   | When the run finished.                                            |
| `error`      | `Error?`  | The error, if the run failed.                                     |
| `result`     | `any?`    | The return value, if the run succeeded.                           |

## Notes

* All listeners receive a `TaskContext`, even for non-execution events like `task:stopped` (where `execution` is absent).
* **Background tasks** emit the same events with the same context, relayed from the worker process. They also emit `task:failed` if their daemon dies unexpectedly; node-cron does not auto-restart, so react to it if you want to recover:

  ```js
  task.on('task:failed', (ctx) => {
    console.error('daemon died:', ctx.error?.message);
    task.start(); // restart manually
  });
  ```
* Listening to `execution:missed` also **suppresses** the default missed-execution warning, since node-cron assumes you're handling it. See [Logging](/logging#suppressing-the-missed-execution-warning).

## Next steps

* **[Background Tasks](/background-tasks)**: run jobs in isolated processes (same events apply).
* [Logging](/logging): route the warnings and errors behind these events through your own logger.

---

---
url: /background-tasks.md
description: >-
  Run node-cron jobs in isolated forked processes so heavy work never blocks
  your main event loop. Covers task files, scheduling, events, and
  executeTimeout.
---

# Background Tasks

When a job is CPU-heavy or long-running, executing it inline can block your main event loop, and node-cron will warn you about [missed executions](/logging#suppressing-the-missed-execution-warning). **Background tasks** solve this by running the job in a separate forked process (via Node's `child_process`), isolated from your application.

You opt into a background task simply by passing a **file path** instead of a function to `cron.schedule`. Everything else (the lifecycle, events, and most options) works exactly the same.

## 1. Create a task file

Write a module that exports a `task` function. This holds the logic to run on schedule.

::: code-group

```js [ESM]
// ./tasks/my-task.js
export function task() {
  return 'Hello from a background task!';
}
```

```js [CommonJS]
// ./tasks/my-task.js
exports.task = () => {
  return 'Hello from a background task!';
};
```

:::

The task function receives the same [`TaskContext`](/event-listening#taskcontext) as an inline task:

```js
// ./tasks/my-task.js
export function task(ctx) {
  console.log('scheduled for:', ctx.dateLocalIso);
}
```

## 2. Schedule it by path

Pass the path where you'd pass a function. Relative paths are resolved from the file that calls `schedule`.

```js
import cron from 'node-cron';

const task = cron.schedule('*/5 * * * * *', './tasks/my-task.js');
```

node-cron forks a process, loads your task file, and schedules it there.

## Control and events

A background task implements the same [`ScheduledTask`](/task-lifecycle) interface as an inline task, with one difference: because it crosses a process boundary, its control methods are **asynchronous** and return Promises.

```js
import cron from 'node-cron';

const task = cron.schedule('*/5 * * * * *', './tasks/my-task.js');

await task.stop();    // terminates the child process
await task.start();   // re-forks and resumes
await task.destroy(); // kills the process and removes the task

task.getStatus();     // synchronous: 'idle', 'running', etc.
```

It emits the [same lifecycle events](/event-listening), relayed from the worker to the parent process:

```js
task.on('execution:failed', (ctx) => {
  console.error('background job failed:', ctx.execution?.error?.message);
});
```

## Manual execution and `executeTimeout`

Call `execute()` to run the task immediately. The task **must be started first** (the process needs to exist):

```js
import cron from 'node-cron';

const task = cron.schedule('0 3 * * *', './tasks/backup.js');
const result = await task.execute();
```

By default `execute()` waits as long as the task needs. To guard against a worker that never reports back, set `executeTimeout` (milliseconds), and `execute()` then rejects if the run doesn't finish in time:

```js
import cron from 'node-cron';

const task = cron.schedule('0 3 * * *', './tasks/backup.js', {
  executeTimeout: 60_000, // reject if a manual execute() exceeds 60s
});
```

## Start handshake and `startTimeout`

Starting a background task forks the daemon and imports your task file. If the file doesn't load and start within `startTimeout` (default `5000` ms), `start()` rejects with a timeout error. A task file with a large dependency graph, or one that is transpiled on load, can legitimately need longer:

```js
import cron from 'node-cron';

const task = cron.schedule('0 3 * * *', './tasks/backup.js', {
  startTimeout: 20_000, // allow a slow-loading task file more time to boot
});
```

If the file fails to load (missing file, or a runtime that can't run it, e.g. an `enum` in a `.ts` file under Node's strip-only TypeScript support), `start()` rejects with the **real** error so you can see what went wrong, rather than a generic timeout. Make sure the task file runs on its own first (e.g. `node ./tasks/backup.js`); if it needs a loader such as `tsx` or `ts-node`, the forked process needs it too, or use a compiled `.js` file.

## Limitations

* **Per-task `logger` is not supported.** A logger is a function-bearing object and can't cross the process boundary. The worker forwards its events to the parent, which does the logging using the **global** logger. Use [`setLogger`](/logging#setting-a-global-logger), or call `setLogger` inside the task file itself. See [Logging](/logging#per-task-logger).
* The task function lives in its **own file**; you can't pass an inline closure.
* Data passed across the boundary is serialized, so event payloads contain plain data (errors are reconstructed on the parent side).

## How it works internally

When a background task starts, node-cron forks a process and launches a small **daemon** that loads your task file and schedules it with the same scheduler used for inline tasks. Parent and child communicate over `child_process` messages (`task:start`, `task:stop`, `task:execute`, and event relays), keeping status and execution in sync across the boundary. Stopping or destroying the task terminates the child process.

## Next steps

* **[Logging](/logging)**: essential for background tasks, since logging happens in the parent.
* [Distributed Coordination](/distributed-coordination): run a background task on one instance per fire across a fleet.
* [Cookbook](/cookbook): practical recipes, including a backup job.

---

---
url: /distributed-coordination.md
description: >-
  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.
---

# Distributed Coordination

The moment you run more than one copy of your app, cron gets awkward. Three replicas behind a load balancer, a PM2 cluster, a Kubernetes Deployment scaled to 4 pods, a blue/green rollout with both colors live for a minute, all of them have the same code, so all of them schedule the same job, and the nightly backup runs **four times** instead of once.

`distributed: true` solves that: the task fires on exactly **one instance per scheduled time**, across the whole fleet.

```js
import cron from 'node-cron';

cron.schedule('0 3 * * *', runNightlyBackup, {
  name: 'nightly-backup',
  distributed: true,
});
```

Two things are required and one is the question that drives everything else:

* It is **opt-in per task** (`distributed: true`); other tasks keep running everywhere.
* It needs a **`name`** (it forms the coordination key shared across instances; the auto-generated id is per-process and can't coordinate).
* And it asks one question on every fire: **"should *this* instance run *this* time?"** The thing that answers is the **run coordinator**.

## The default: one designated runner

Out of the box, node-cron answers that question with an environment variable, `NODE_CRON_RUN`, no extra dependencies, no Redis. You designate **one** instance as the runner:

```bash
# instance A
NODE_CRON_RUN=true   node app.js

# instances B, C, D
NODE_CRON_RUN=false  node app.js
```

Now the backup runs only on instance A; B, C, and D skip it. This is the simplest correct answer to "stop running my cron N times," and for many fleets it's all you need: your orchestrator already decides which pod is special (a `StatefulSet`, a single-replica `Deployment`, a dedicated worker dyno), so let it set the flag.

There is **no default value**. If a `distributed` task is scheduled and `NODE_CRON_RUN` is unset (or isn't exactly `'true'`/`'false'`), node-cron **throws at schedule time**, on startup, not silently at 3 a.m.:

```
node-cron: a `distributed` task needs NODE_CRON_RUN set to 'true' or 'false'.
Set it to 'true' on exactly one instance and 'false' on the others, or provide
a coordinator via cron.setRunCoordinator(...).
```

This is deliberate. A silent default could only do one of two wrong things, run everywhere (the duplicates you came here to fix) or run nowhere (a backup that quietly never happens). Failing loudly on deploy is the safe choice.

::: tip This is not high availability
The env-var default is a *single designated runner*. If instance A is down at 3 a.m., the backup doesn't run, B, C, and D were told `false`. For a fleet where **any** instance can take over, read on.
:::

## The guarantee

With coordination in place, node-cron guarantees **no concurrent execution across instances**, effectively *once per fire* when the instances' clocks are in sync.

It is **not** a hard exactly-once: under a crash-and-retry, or large clock skew between instances, a fire could still run more than once. Treat distributed tasks as **idempotent** (safe to run twice) and you're covered for the rare edge. This is a coordination primitive, not a transactional queue, if you need durable, exactly-once job semantics, reach for a queue like BullMQ.

## High availability: a custom run coordinator

The env-var default trades availability for simplicity. To let **any** instance run a fire, only never two at once, you provide a **run coordinator** backed by something the whole fleet shares (typically Redis). Now there's no special instance: every replica races for each fire, exactly one wins, and if the winner is down another takes over.

A coordinator is just an object that answers the question:

```ts
interface RunCoordinator {
  // true  -> this instance runs the fire identified by `key`
  // false -> skip it (another instance handles it)
  // throw -> fail closed (skip), e.g. the backend is unreachable
  shouldRun(key: string, ttlMs: number): boolean | Promise<boolean>;

  // called after the run completes (success or failure); e.g. release a lock
  onComplete?(key: string): void | Promise<void>;
}
```

Register one globally with `setRunCoordinator` and it's used for every `distributed` task instead of the env-var default. Under the hood a lease-based coordinator turns `shouldRun` into an atomic "claim this key" and `onComplete` into a safe release, so for the fire keyed `nightly-backup:2026-06-17T03:00:00.000Z`, the first instance to claim it wins and the rest get `false`.

### The Redis coordinator

The official Redis implementation ships as a separate package, [`@node-cron/redis-coordinator`](https://www.npmjs.com/package/@node-cron/redis-coordinator), so the core stays dependency-free.

You install it alongside `node-cron` and **the Redis client you already use** (it supports both [`ioredis`](https://github.com/redis/ioredis) and [`node-redis`](https://github.com/redis/node-redis) v4, and auto-detects which one you passed):

::: code-group

```bash [node-redis]
npm install @node-cron/redis-coordinator node-cron redis
```

```bash [ioredis]
npm install @node-cron/redis-coordinator node-cron ioredis
```

:::

It needs **node-cron >= 4.4.1** (the peer dependency) and has **zero runtime dependencies** of its own: you pass in a client you already created and connected, and the coordinator just uses it (your TLS, Sentinel, Cluster, auth, and retry config stay yours).

```js
import { createClient } from 'redis';
import cron, { setRunCoordinator } from 'node-cron';
import { RedisLockCoordinator } from '@node-cron/redis-coordinator';

const redis = createClient(); // your client, your connection
await redis.connect();

setRunCoordinator(new RedisLockCoordinator(redis));

// Deploy on N instances: only one runs each 3am fire, and it survives the loss of any node.
cron.schedule('0 3 * * *', runNightlyBackup, {
  name: 'nightly-backup',
  distributed: true,
  distributedLease: 5 * 60_000, // the backup can take up to ~5 minutes
});
```

With `ioredis` it's the same, just hand in the client you have:

```js
import Redis from 'ioredis';
setRunCoordinator(new RedisLockCoordinator(new Redis()));
```

Options: `keyPrefix` (default `node-cron:lock:`), `clientType` (`'auto'` | `'ioredis'` | `'node-redis'`), and a `logger`. It also exposes a `healthCheck()` that compares the local clock to the Redis server clock, see [clock skew](#clock-skew) below.

::: tip Other backends
`@node-cron/redis-coordinator` is just one implementation of the `RunCoordinator` interface above. Any object with `shouldRun`/`onComplete` works, so you can back coordination with Postgres, etcd, or anything your fleet shares.
:::

### Per-task coordinator

A coordinator can also be set on a single task, overriding the global one:

```js
cron.schedule('*/5 * * * *', syncInventory, {
  name: 'sync-inventory',
  distributed: true,
  runCoordinator: myCoordinator, // wins over setRunCoordinator() and the env default
});
```

Resolution order: per-task `runCoordinator` → global `setRunCoordinator` → the env-var default.

## Knowing when an instance skips

When an instance is **not** the one chosen to run a fire, it emits [`execution:skipped`](/event-listening) instead of running. The context carries a `reason`:

```js
task.on('execution:skipped', (ctx) => {
  if (ctx.reason === 'coordinator-error') {
    // the coordinator failed (e.g. Redis down) and we failed closed.
    // this is the one to alert on: the fire may not have run anywhere.
    alert('cron coordination is failing', ctx);
  }
  // ctx.reason === 'not-elected' is the healthy case: another instance ran it.
});
```

| `reason`             | Meaning                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `'not-elected'`      | Healthy. Another instance was chosen for this fire.                                      |
| `'coordinator-error'`| The coordinator threw (e.g. the backend was unreachable). node-cron **failed closed** and skipped, so the fire may not have run on any instance. Alert on this. |

The instance that *does* run emits the normal [`execution:started` → `execution:finished`](/event-listening) sequence, so "did this instance run it?" is just "did I get `execution:started`?", no extra event needed.

## `distributedLease`

Lease-based coordinators (like a Redis lock) hold the claim for a safety window in case the winner crashes mid-run without releasing it. `distributedLease` (ms, default `30000`) sets that lease, and it **must exceed the task's run time**, or the lease can expire mid-run and a late-arriving instance (delayed by clock skew, GC, or a blocked event loop) could re-acquire the expired key and start a second copy. The env-var default ignores it.

```js
cron.schedule('0 3 * * *', runNightlyBackup, {
  name: 'nightly-backup',
  distributed: true,
  distributedLease: 5 * 60_000, // the backup can take up to ~5 minutes
});
```

::: warning Account for jitter
The lease is acquired at the scheduled time, **before** any [`maxRandomDelay`](/scheduling-options) jitter is applied (the jitter only runs on the instance that won the lock, never affecting which instance wins). So the key stays claimed for `jitter + run time`, not just the run time. When you combine `distributed` with `maxRandomDelay`, size the lease for both:

```
distributedLease  >  maxRandomDelay + the task's max run time
```

Otherwise the lease can expire while the winner is still waiting out its jitter or running, reopening the double-run window above.
:::

## Clock skew

Coordination keys are built from the **scheduled time** (`name:fireTimeISO`), so every instance must agree on what time it is. If two instances' clocks drift apart, they compute different keys for the "same" fire, claim different locks, and both run, the no-concurrent guarantee quietly degrades. Keep your fleet on NTP.

To catch drift before it bites, `@node-cron/redis-coordinator` exposes a `healthCheck()` that compares the local clock to the Redis server clock (a shared reference) and reports the skew:

```js
const coordinator = new RedisLockCoordinator(redis);
cron.setRunCoordinator(coordinator);

const { ok, driftMs } = await coordinator.healthCheck(); // default threshold 1000ms
if (!ok) {
  console.warn(`clock skew vs Redis is ${driftMs}ms; distributed coordination may be unreliable`);
}
```

Run it at startup (or on a health endpoint) to surface a misconfigured clock as an alert rather than a duplicate run.

## Background tasks work too

`distributed` works for [background tasks](/background-tasks) exactly as for inline ones, you set the coordinator in your main process and it applies transparently. Internally the forked daemon can't hold the coordinator (it lives across a process boundary), so it asks the parent over IPC, and the parent runs the real coordinator. The shared backend still arbitrates across the fleet; you don't configure anything extra.

```js
// in your main process
setRunCoordinator(new RedisLockCoordinator(redis));

cron.schedule('0 3 * * *', './tasks/backup.js', {
  name: 'nightly-backup',
  distributed: true,
});
```

## A note on `maxExecutions`

[`maxExecutions`](/scheduling-options) is counted **per instance**. With a per-fire coordinator (the HA case), each instance only counts the fires it won, so the fleet total can exceed your limit. With the single-runner env-var default it behaves as expected, only the designated instance runs and counts.

## How it works internally

On each fire of a `distributed` task, node-cron builds a key from the task's `name` and the exact scheduled time (`name:fireTimeISO`), so every instance computes the **same** key for the **same** fire. It calls `shouldRun(key, ttl)`; on `true` it runs the task and then calls `onComplete(key)`; on `false` (or a thrown error) it emits `execution:skipped` and moves on. The coordinator is where cross-instance agreement happens, node-cron itself stays a scheduler.

## Next steps

* **[Events & Observability](/event-listening)**: handle `execution:skipped` and the rest of the lifecycle.
* [Background Tasks](/background-tasks): run the work in an isolated process; coordination still applies.
* [Scheduling Options](/scheduling-options): the full list of options, including `distributed`, `runCoordinator`, and `distributedLease`.

---

---
url: /logging.md
description: >-
  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.
---

# Logging

node-cron writes a few internal messages, most notably a warning when a
scheduled execution is missed (usually caused by blocking I/O or high CPU in
the same process). You can route these messages through your own logger and
control the missed-execution warning.

## The `Logger` interface

A logger is any object that implements these four methods. You don't need to
extend or `implements` anything; any matching object works (structural typing).

```ts
interface Logger {
  info(message: string): void;
  warn(message: string): void;
  error(message: string | Error, err?: Error): void;
  debug(message: string | Error, err?: Error): void;
}
```

> 🛈 `error` and `debug` may receive either a `string` or an `Error`, so handle
> both in your adapter.

## Setting a global logger

Use `setLogger` to replace the built-in console logger for the whole module:

```js
import cron, { setLogger } from 'node-cron';

setLogger({
  info:  (msg) => myLogger.info(msg),
  warn:  (msg) => myLogger.warn(msg),
  error: (msg) => myLogger.error(msg),
  debug: (msg) => myLogger.debug(msg),
});
```

In CommonJS:

```js
const cron = require('node-cron');
cron.setLogger({ /* ... */ });
```

### Using winston / pino

Both expose `info`/`warn`/`error`/`debug`, so they are almost a drop-in:

```js
import pino from 'pino';
import { setLogger } from 'node-cron';

const log = pino();

setLogger({
  info:  (m) => log.info(m),
  warn:  (m) => log.warn(m),
  error: (m, e) => log.error(e ?? m),
  debug: (m) => log.debug(m),
});
```

### Silencing all output

Pass a logger whose methods do nothing:

```js
import { setLogger } from 'node-cron';

const noop = () => {};
setLogger({ info: noop, warn: noop, error: noop, debug: noop });
```

## Per-task logger

You can also override the logger for a single task with the `logger` option. It
takes precedence over the global logger for that task:

```js
const task = cron.schedule('* * * * *', () => {}, {
  logger: myTaskLogger,
});
```

> 🛈 The per-task `logger` is **not** supported for [Background Tasks](/background-tasks),
> because it cannot cross the worker process boundary. For background tasks, use
> the global `setLogger` (the parent process does the logging from the worker's
> events) or call `setLogger` inside the task file itself.

## Suppressing the "missed execution" warning

When a scheduled execution is missed, node-cron logs:

```
[NODE-CRON] [WARN] missed execution at <time>! Possible blocking IO or high CPU ...
```

This warning is intentional. It surfaces environments where blocking I/O or CPU
pressure is causing node-cron to miss runs. It is suppressed automatically when
you take ownership of the signal, in either of two ways:

### 1. Listen to the `execution:missed` event

If a listener is attached, node-cron assumes you are handling it and stays quiet:

```js
const task = cron.schedule('* * * * *', () => {});

task.on('execution:missed', (ctx) => {
  // you decide what to do: log it, alert, ignore, etc.
  metrics.increment('cron.missed', { date: ctx.date });
});
```

See [Event Listening](/event-listening) for the full event list and payload.

### 2. Opt out explicitly with `suppressMissedWarning`

If you simply want the warning off (without listening), set the option:

```js
const task = cron.schedule('* * * * *', () => {}, {
  suppressMissedWarning: true,
});
```

> ⚠️ Suppressing the warning hides a real signal: your task may be missing
> executions due to blocking I/O or high CPU. Prefer fixing the root cause, or
> running the job as a [Background Task](/background-tasks), before silencing it.

## Next steps

* **[Cookbook](/cookbook)**: practical, copy-paste recipes for common jobs.
* [API Reference](/api-reference): the full surface of the node-cron module.

---

---
url: /nestjs.md
description: >-
  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.
---

# NestJS

NestJS ships its own scheduler, [`@nestjs/schedule`](https://docs.nestjs.com/techniques/task-scheduling) (backed by the `cron` package). It gives you `@Cron`, `@Interval` and `@Timeout`, and stops there.

[`@node-cron/nestjs`](https://www.npmjs.com/package/@node-cron/nestjs) is a **drop-in replacement** backed by node-cron: the **same** decorators, the same `ScheduleModule` and `SchedulerRegistry`, plus everything node-cron adds, distributed scheduling, background tasks in a forked process, lifecycle events, execution caps and jitter. Migrating is a **one-line import swap**.

## `@nestjs/schedule` vs `@node-cron/nestjs`

| | `@nestjs/schedule` | `@node-cron/nestjs` |
| --- | --- | --- |
| `@Cron` / `@Interval` / `@Timeout` | yes | yes (same API) |
| `CronExpression` enum | yes | yes (identical values) |
| `SchedulerRegistry` | yes | yes (returns a node-cron [`ScheduledTask`](/task-lifecycle)) |
| Skip overlapping runs | `waitForCompletion` | `waitForCompletion` / `noOverlap` |
| Lifecycle [events](/event-listening) (`execution:finished`, …) | no | yes |
| [Run once across a fleet](/distributed-coordination) | no | `distributed: true` |
| Per-fire HA coordination (Redis) | no | [`@node-cron/redis-coordinator`](/distributed-coordination#the-redis-coordinator) |
| [Background tasks](/background-tasks) (forked process) | no | `@BackgroundCron` |
| Cap executions / random jitter | no | `maxExecutions`, `maxRandomDelay` |
| DST-correct IANA timezones | partial | yes ([Timezones & DST](/timezones-and-dst)) |

## Install

`node-cron` is a peer dependency, so install it alongside the package (the NestJS peers are already in your app):

```bash
npm install @node-cron/nestjs node-cron
```

It supports NestJS 9, 10 and 11, and needs **node-cron >= 4.4.1**.

## Quickstart

Import `ScheduleModule.forRoot()` once, then decorate provider methods. This is identical to `@nestjs/schedule`.

```ts
// app.module.ts
import { Module } from '@nestjs/common';
import { ScheduleModule } from '@node-cron/nestjs';
import { TasksService } from './tasks.service';

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

```ts
// tasks.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { Cron, Interval, Timeout, CronExpression } from '@node-cron/nestjs';

@Injectable()
export class TasksService {
  private readonly logger = new Logger(TasksService.name);

  @Cron(CronExpression.EVERY_30_SECONDS)
  handleCron() {
    this.logger.log('Called every 30 seconds');
  }

  @Interval(10_000)
  handleInterval() {
    this.logger.log('Called every 10 seconds');
  }

  @Timeout(5_000)
  handleTimeout() {
    this.logger.log('Called once, 5 seconds after startup');
  }
}
```

The decorated methods run inside your NestJS process with full dependency injection, exactly as they do with `@nestjs/schedule`.

## `@Cron` options

`@Cron(expression, options)` accepts everything `@nestjs/schedule` does, plus node-cron's extras:

```ts
@Cron('0 3 * * *', {
  name: 'nightly-backup',     // look it up via SchedulerRegistry
  timeZone: 'America/Sao_Paulo',
  waitForCompletion: true,    // alias: noOverlap — skip a run if the previous is still going
  initialDelay: 2_000,        // delay the first run after bootstrap (ms)

  // node-cron extras:
  distributed: true,          // run once across a fleet (see below)
  distributedLease: 5 * 60_000,
  maxExecutions: 10,          // destroy the job after N runs
  maxRandomDelay: 1_000,      // jitter (ms) to spread fleet load
})
handleCron() {}
```

See [Scheduling Options](/scheduling-options) for the full semantics of each.

## Inspecting and controlling jobs: `SchedulerRegistry`

Inject `SchedulerRegistry` and look a job up by `name`. The key upgrade: `getCronJob(name)` returns a node-cron [`ScheduledTask`](/task-lifecycle), so you get its full API.

```ts
import { Injectable } from '@nestjs/common';
import { SchedulerRegistry } from '@node-cron/nestjs';

@Injectable()
export class JobsService {
  constructor(private readonly registry: SchedulerRegistry) {}

  inspect() {
    const task = this.registry.getCronJob('nightly-backup');

    task.getNextRun();   // Date | null
    task.getStatus();    // 'idle' | 'running' | 'stopped' | 'destroyed'
    task.getNextRuns(3); // preview the next 3 fire times

    task.on('execution:failed', (ctx) => {
      // observe failures, missed runs, skipped (distributed) runs, etc.
    });

    return task.execute(); // run it now, off-schedule
  }
}
```

These methods come from [Task Lifecycle & Status](/task-lifecycle) and [Events & Observability](/event-listening).

## Background tasks

A `@BackgroundCron` runs in a **forked child process** with its own event loop, so heavy or blocking work never stalls your NestJS process. This is a node-cron feature `@nestjs/schedule` does not have.

Unlike `@Cron` (a method whose body runs inline), `@BackgroundCron` decorates a **property whose value is the path to the task file**. The cleanest layout keeps the task and its schedule in one self-referencing file:

```ts
// report.task.ts
import { Injectable } from '@nestjs/common';
import { BackgroundCron, type TaskContext } from '@node-cron/nestjs';

// (A) Runs in the forked CHILD process. A plain function, no Nest DI here:
//     node-cron imports this compiled file and calls `task`.
export const task = async (ctx: TaskContext) => {
  // heavy, isolated work
};

// (B) Runs in the MAIN process. The property holds this file's own path.
@Injectable()
export class ReportTask {
  @BackgroundCron('0 * * * *', { name: 'report' })
  taskFile = __filename;
}
```

Register `ReportTask` in a module's `providers` and that's it: on bootstrap it's added to `SchedulerRegistry`, forked, started, and cleaned up on shutdown.

::: warning A few rules

* The task file **must `export const task`** — that named export is what the child runs. The `@Injectable` class is ignored by the child.
* Point the property at the **compiled `.js`**: `__filename` (CommonJS, the `nest build` default) or `fileURLToPath(import.meta.url)` (ESM).
* `export const task` gets **no Nest DI** (it's a separate process). It can use `process.env` and open its own connections. If it truly needs DI, bootstrap a lean standalone context inside `task` with `NestFactory.createApplicationContext` (do not bootstrap your full `AppModule`, or its `ScheduleModule` re-schedules everything in the child).
  :::

All `@Cron` options work here too, including `distributed`. See [Background Tasks](/background-tasks) for how the forked daemon works.

## Distributed scheduling

To run a job **once per fire across a fleet**, give the module a [run coordinator](/distributed-coordination) and mark the job `distributed: true`. For high-availability, per-fire coordination, use [`@node-cron/redis-coordinator`](/distributed-coordination#the-redis-coordinator):

```ts
// app.module.ts
import { Module } from '@nestjs/common';
import { ScheduleModule } from '@node-cron/nestjs';
import { RedisLockCoordinator } from '@node-cron/redis-coordinator';
import { createClient } from 'redis';

const redis = createClient();
await redis.connect();

@Module({
  imports: [
    ScheduleModule.forRoot({ coordinator: new RedisLockCoordinator(redis) }),
  ],
})
export class AppModule {}
```

```ts
@Cron('0 3 * * *', { name: 'nightly-backup', distributed: true })
handleBackup() {
  // runs on exactly one instance per fire
}
```

Without a coordinator, `distributed` jobs fall back to node-cron's `NODE_CRON_RUN` env-var default (a single designated runner). The full model, the guarantee, and the `execution:skipped` event are covered in [Distributed Coordination](/distributed-coordination).

## Migrating from `@nestjs/schedule`

For most apps, migrating is a **single line**, swap the import:

```ts
- import { ScheduleModule, Cron, Interval, Timeout, CronExpression, SchedulerRegistry } from '@nestjs/schedule';
+ import { ScheduleModule, Cron, Interval, Timeout, CronExpression, SchedulerRegistry } from '@node-cron/nestjs';
```

Your decorated methods, the `CronExpression` values, and `ScheduleModule.forRoot()` all stay the same. Two things differ on purpose:

### `getCronJob(name)` returns a node-cron `ScheduledTask`

This is the upgrade, but it's a different shape than the `cron` package's `CronJob`. Update any code that read the old API:

| `@nestjs/schedule` (`CronJob`) | `@node-cron/nestjs` (`ScheduledTask`) |
| --- | --- |
| `job.nextDate()` / `job.nextDates(n)` | [`task.getNextRun()`](/task-lifecycle#getnextrun) / [`task.getNextRuns(n)`](/task-lifecycle#getnextruns-count) |
| `job.running` (boolean) | [`task.getStatus()`](/task-lifecycle#getstatus) (`'running'` / `'idle'` / `'stopped'`) or [`task.isBusy()`](/task-lifecycle#isbusy) |
| `job.lastDate()` | not stored; observe runs via [`task.on('execution:finished', …)`](/event-listening) |
| `job.start()` / `job.stop()` | `task.start()` / `task.stop()` (same) |
| `job.fireOnTick()` | [`task.execute()`](/task-lifecycle#execute) |

### `utcOffset` is not supported

node-cron schedules by IANA timezone, not by raw offset. If a `@Cron` sets `utcOffset`, it is **ignored with a warning** and the job still runs:

```
WARN [Scheduler] Cron job "..." sets `utcOffset`, which node-cron does not
support. It is ignored; use `timeZone` instead.
```

Replace `utcOffset: -180` with `timeZone: 'America/Sao_Paulo'` (or the relevant IANA name). This is more robust anyway, it follows daylight-saving transitions correctly. See [Timezones & DST](/timezones-and-dst).

Everything else, decorators, options you already used, registry method names (`getCronJob`, `addCronJob`, `deleteCronJob`, …), behaves the same.

## Next steps

* [Events & Observability](/event-listening): react to `execution:finished`, `failed`, `missed`, and more on any job.
* [Distributed Coordination](/distributed-coordination): the full guide to `distributed: true` and coordinators.
* [Background Tasks](/background-tasks): how the forked daemon behind `@BackgroundCron` works.
* [Cookbook](/cookbook): a complete NestJS recipe.

---

---
url: /fastify.md
description: >-
  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.
---

# Fastify

[`@node-cron/fastify`](https://www.npmjs.com/package/@node-cron/fastify) is the **official** Fastify plugin for node-cron. It registers like [`@fastify/schedule`](https://github.com/fastify/fastify-schedule), the same `fastify.register`, the same `fastify.scheduler` decorator, the same start-on-ready / stop-on-close lifecycle, but backed by node-cron, so jobs are described with **real cron expressions** and you get distributed-ready scheduling, background tasks, timezones and per-execution events.

## `@fastify/schedule` vs `@node-cron/fastify`

| | `@fastify/schedule` (toad-scheduler) | `@node-cron/fastify` (node-cron) |
| --- | --- | --- |
| `register` + `fastify.scheduler` + lifecycle | yes | yes (same) |
| Job definition | toad-scheduler `Job` objects | cron expressions (with seconds) |
| [Run once across a fleet](/distributed-coordination) | no | `distributed: true` + a coordinator |
| [Background tasks](/background-tasks) (forked process) | no | `run: '<file path>'` |
| IANA timezones (DST-correct) | no | `timezone` option |
| Per-execution [events](/event-listening) | no | `task.on('execution:*')` |
| Overlap control / execution caps | limited | `noOverlap`, `maxExecutions` |

## Install

`fastify` (v5) and `node-cron` are peer dependencies, so the plugin shares the single copy your app already has:

```bash
npm install @node-cron/fastify node-cron fastify
```

## Quick start

Register the plugin and declare jobs in `tasks`. They're created on registration and **start when Fastify emits `onReady`**, then are **destroyed on `onClose`**.

```ts
import Fastify from 'fastify';
import { fastifyNodeCron } from '@node-cron/fastify';

const app = Fastify();

await app.register(fastifyNodeCron, {
  tasks: [
    {
      cron: '0 3 * * *', // every day at 03:00
      name: 'nightly-backup',
      run: async () => {
        await runBackup();
      },
    },
  ],
});

await app.listen({ port: 3000 });
```

## Scheduling imperatively

The plugin decorates the instance as `fastify.scheduler` (alias `fastify.cron`, the same object), so you can schedule from a route or another plugin:

```ts
app.post('/reports/enable', async () => {
  app.scheduler.schedule('*/5 * * * *', () => sendReport(), { name: 'report' });
  return { scheduled: true };
});
```

## Plugin options

```ts
await app.register(fastifyNodeCron, {
  tasks: [ /* FastifyNodeCronTaskDefinition[] */ ],
  runCoordinator,   // RunCoordinator for distributed tasks (process-wide)
  logger,           // custom logger (process-wide); defaults to the Fastify logger
  autoStart: true,  // start tasks on onReady (default true)
});
```

| Option | Type | Description |
| --- | --- | --- |
| `tasks` | `FastifyNodeCronTaskDefinition[]` | Jobs to register at startup. Each is `{ cron, run, ...options }`, where `options` is any [node-cron task option](/scheduling-options). |
| `runCoordinator` | `RunCoordinator` | Coordinator for `distributed: true` tasks. See [Distributed Coordination](/distributed-coordination). |
| `logger` | `Logger` | Custom [logger](/logging), applied process-wide. |
| `autoStart` | `boolean` | When `false`, nothing starts automatically; drive it via `app.scheduler.start()` / `stop()`. Defaults to `true`. |

A task definition is node-cron's options plus `cron` and `run`:

```ts
{
  cron: '0 3 * * *',          // required: the cron expression
  run: () => doWork(),        // required: an inline function OR a file path (background task)
  name: 'nightly-backup',     // any node-cron option from here on
  timezone: 'America/Sao_Paulo',
  distributed: true,
  noOverlap: true,
  maxExecutions: 10,
}
```

## The `scheduler` decorator

`fastify.scheduler` exposes a small node-cron-native API:

```ts
app.scheduler.schedule(expression, run, options?); // -> ScheduledTask
app.scheduler.getTask(id);                          // by node-cron id
app.scheduler.getTaskByName(name);                  // by your name
app.scheduler.getTasks();                           // Map<id, ScheduledTask>
app.scheduler.start();   // start owned tasks
app.scheduler.stop();    // stop owned tasks (keep them)
app.scheduler.close();   // destroy owned tasks
app.scheduler.cron;      // the underlying node-cron instance
```

`schedule` returns a node-cron [`ScheduledTask`](/task-lifecycle), so you get its full API, including [lifecycle events](/event-listening):

```ts
const task = app.scheduler.schedule('* * * * *', () => work(), { name: 'work' });

task.on('execution:started', () => app.log.info('work started'));
task.on('execution:failed', (ctx) => app.log.error(ctx.execution?.error));

task.getNextRun(); // Date | null
```

## Background tasks

Point `run` at a **file path** instead of a function and the job runs in a [forked child process](/background-tasks), so heavy or blocking work never stalls Fastify's event loop. The file must `export const task`:

```ts
// backup.task.js  —  export const task = async (ctx) => { /* heavy work */ };

await app.register(fastifyNodeCron, {
  tasks: [
    { cron: '0 3 * * *', name: 'backup', run: new URL('./backup.task.js', import.meta.url).pathname },
  ],
});
```

Use an absolute path to the compiled file (`__filename` in CommonJS, or `fileURLToPath(import.meta.url)` / `new URL(...).pathname` in ESM). See [Background Tasks](/background-tasks) for the details.

## Distributed scheduling

To run a job once per fire across a fleet, pass a [run coordinator](/distributed-coordination) to the plugin and mark the job `distributed: true`:

```ts
import { RedisLockCoordinator } from '@node-cron/redis-coordinator';

await app.register(fastifyNodeCron, {
  runCoordinator: new RedisLockCoordinator(redis),
  tasks: [
    { cron: '0 3 * * *', name: 'nightly-backup', distributed: true, run: () => runBackup() },
  ],
});
```

The plugin makes a task **coordination-ready**; the per-fire, fleet-wide election is the coordinator's job. Without one, `distributed` tasks fall back to node-cron's `NODE_CRON_RUN` env-var default (a single designated runner). The full model is in [Distributed Coordination](/distributed-coordination).

## Migrating from `@fastify/schedule`

Registration, the decorator name, and the lifecycle are the same. What changes is how you describe a job: a **cron expression** instead of a toad-scheduler `Job`.

```ts
// Before — @fastify/schedule + toad-scheduler
import { fastifySchedule } from '@fastify/schedule';
import { AsyncTask, SimpleIntervalJob } from 'toad-scheduler';

await app.register(fastifySchedule);
const task = new AsyncTask('poll', () => pollForData());
app.scheduler.addSimpleIntervalJob(new SimpleIntervalJob({ minutes: 5 }, task));
```

```ts
// After — @node-cron/fastify
import { fastifyNodeCron } from '@node-cron/fastify';

await app.register(fastifyNodeCron);
app.scheduler.schedule('*/5 * * * *', () => pollForData(), { name: 'poll' });
```

Interval jobs map to cron expressions. For sub-minute work, node-cron's 6-field expression has seconds, e.g. `'*/20 * * * * *'` for every 20 seconds.

## Next steps

* [Events & Observability](/event-listening): react to `execution:finished`, `failed`, `missed`, and more.
* [Distributed Coordination](/distributed-coordination): run a job once across a fleet.
* [Background Tasks](/background-tasks): how the forked daemon behind a file-path `run` works.
* [Scheduling Options](/scheduling-options): every task option you can pass.

---

---
url: /cron-translate.md
description: >-
  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.
---

# Plain English to Cron

[`cron-translate`](https://github.com/node-cron/cron-translate) is a companion package that converts plain English into the cron expressions node-cron runs, and back again. It is zero-dependency, TypeScript-native, and built specifically for node-cron's 6-field format.

Two functions:

* **`toCron(text)`** turns a phrase like `every weekday at 6pm` into `0 0 18 * * 1-5`.
* **`toHuman(cron)`** turns a cron expression back into a readable sentence.

## Install

```bash
npm install cron-translate
```

```js
import { toCron } from 'cron-translate';

toCron('every day at 9am'); // "0 0 9 * * *"
```

It ships both ESM and CommonJS builds with type declarations, and requires Node.js >= 20.

## Using it with node-cron

The whole point is that the output drops straight into `cron.schedule`:

```js
import cron from 'node-cron';
import { toCron } from 'cron-translate';

cron.schedule(toCron('every weekday at 6pm'), () => {
  runDailyReport();
});
```

No more counting fields or second-guessing whether `*/5` goes in minutes or hours.

## English to cron

A schedule is a sentence: one frequency, plus optional clauses for time, day, and month.

```
every <frequency> [at <time>] [on <day>] [in <month>]
```

| Input | Cron |
|---|---|
| `every minute` | `0 * * * * *` |
| `every 5 minutes` | `0 */5 * * * *` |
| `every day at noon` | `0 0 12 * * *` |
| `every weekday at 6pm` | `0 0 18 * * 1-5` |
| `every monday at 9am` | `0 0 9 * * 1` |
| `every weekend` | `0 0 0 * * 0,6` |
| `last friday of the month` | `0 0 0 * * 5L` |
| `first monday of the month at 9am` | `0 0 9 * * 1#1` |

Times can be 12-hour (`at 9am`, `at 6:30pm`), 24-hour (`at 14:30`), or words (`at noon`, `at midnight`). Day-parts work as a whole schedule (`every morning`, `every evening`).

### Values, lists, and ranges

Every field accepts a single value, a list, or a range. Address a field by name, or use weekday and month names:

| Example | Cron |
|---|---|
| `at minutes 0, 15, 30 and 45` | `0 0,15,30,45 * * * *` |
| `at minute 1 to 30` | `0 1-30 * * * *` |
| `between 9am and 5pm` | `0 0 9-17 * * *` |
| `on day 1 to 10` | `0 0 0 1-10 * *` |
| `in march and june` | `0 0 0 1 3,6 *` |
| `on monday to friday` | `0 0 0 * * 1-5` |

Lists use `,` or `and`; ranges use `to` or `through`. Names and abbreviations both work (`january` / `jan`, `monday` / `mon`).

### Invalid input is rejected, never guessed

If a phrase can't become a valid cron expression, `toCron` throws a `CronTranslateError` instead of returning a wrong schedule. That covers unrecognized words, conflicting clauses, and out-of-range values (minute `0`-`59`, day `1`-`31`, and so on).

```js
import { toCron, CronTranslateError } from 'cron-translate';

try {
  toCron('the weekday nearest the 15th');
} catch (err) {
  if (err instanceof CronTranslateError) {
    console.error(err.message, err.hint);
  }
}
```

A wrong cron expression runs your job at the wrong time, which is worse than an error. Things standard cron can't express (the `W` nearest-weekday character, counted recurrence like `until christmas`, arbitrary natural language) are turned away on purpose, with a hint pointing back to the [cron syntax](/cron-syntax) reference.

## Cron to English

`toHuman` goes the other way: give it a 5- or 6-field cron expression and it returns a readable sentence.

```js
import { toHuman } from 'cron-translate';

toHuman('0 0 9 * * *');     // "at 9am"
toHuman('0 0 18 * * 1-5');  // "at 6pm on monday to friday"
toHuman('0 */5 9 * * *');   // "every 5 minutes at 9am"
toHuman('0 0 0 * * 5L');    // "last friday of the month"
```

The English is phrased so that `toCron` parses it back to the same expression, so `toCron(toHuman(cron))` returns the original cron. That makes it a natural readback: take a cron a user typed, show them what it means, and let them confirm it before it ships.

## Learn more

Full documentation, the complete grammar, and the source are on GitHub: [node-cron/cron-translate](https://github.com/node-cron/cron-translate).

---

---
url: /cron-tester.md
description: >-
  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.
---

# Cron Expression Tester

Type a cron expression and read it back in plain English, instantly. This runs
[`cron-translate`](/cron-translate) in your browser, the same library you can drop into
your node-cron project. No server, no tracking of what you type.

It uses node-cron's [6-field syntax](/cron-syntax) (`second minute hour day month weekday`).
Five-field expressions work too: the second is assumed to be `0`.

Every test is shareable. The URL updates as you type, so you can copy it (or hit
**Copy shareable link**) and send it to someone. A `?c=` link opens the cron reader
(`/cron-tester?c=0 0 9 * * 1-5`) and a `?t=` link opens the English translator
(`/cron-tester?t=every weekday at 6pm`).

## How it works

The tester is just two function calls from [`cron-translate`](/cron-translate):

```js
import { toHuman, toCron } from 'cron-translate';

toHuman('0 0 9 * * 1-5'); // "at 9am on monday to friday"
toCron('every weekday at 6pm'); // "0 0 18 * * 1-5"
```

`toHuman` is phrased so that `toCron` parses it back to the same expression, so the two
directions round-trip. Once you have an expression you trust, drop it into node-cron:

```js
import cron from 'node-cron';

cron.schedule('0 0 9 * * 1-5', () => {
  runDailyReport();
});
```

See the [cron-translate guide](/cron-translate) for the full grammar, or the
[cron syntax reference](/cron-syntax) for what each field accepts.

---

---
url: /cookbook.md
description: >-
  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.
---

# Cookbook

Practical recipes for common scheduling jobs. Each one is self-contained: copy it, adjust the expression and the work, and run.

New to the API? Start with the [Quickstart](/getting-started) and [Cron Syntax](/cron-syntax).

## Daily backup at 3 AM (background)

Heavy jobs belong in a [background task](/background-tasks) so they don't block your event loop. Run it in a fixed timezone so "3 AM" is unambiguous.

```js
// app.js
import cron from 'node-cron';

const backup = cron.schedule('0 3 * * *', './tasks/backup.js', {
  name: 'daily-backup',
  timezone: 'America/Sao_Paulo',
  noOverlap: true,
});

backup.on('execution:failed', (ctx) => {
  console.error('backup failed:', ctx.execution?.error?.message);
});
```

```js
// tasks/backup.js
export async function task() {
  await dumpDatabase();
  await uploadToStorage();
}
```

## Periodic cleanup every 15 minutes

```js
import cron from 'node-cron';

cron.schedule('*/15 * * * *', async () => {
  const removed = await deleteExpiredSessions();
  console.log(`cleaned up ${removed} expired sessions`);
});
```

## Timezone-aware health check on weekdays

Run only during business hours (09:00–17:00, Mon–Fri) in a specific timezone.

```js
import cron from 'node-cron';

cron.schedule('0 9-17 * * 1-5', async () => {
  const ok = await pingService();
  if (!ok) await notifyOnCall();
}, {
  name: 'business-hours-healthcheck',
  timezone: 'Europe/London',
});
```

## Spread load with jitter

When many instances run the same hourly job, stagger them with up to 30s of random delay to avoid a thundering herd.

```js
import cron from 'node-cron';

cron.schedule('0 * * * *', async () => {
  await refreshSharedCache();
}, {
  maxRandomDelay: 30_000,
});
```

## Retry on failure

React to `execution:failed` and re-run the task with a backoff. `execute()` triggers an immediate, off-schedule run.

```js
import cron from 'node-cron';

const task = cron.schedule('*/10 * * * *', async () => {
  await syncRemoteData(); // throws on failure
});

const MAX_RETRIES = 3;
let attempts = 0;

task.on('execution:failed', async (ctx) => {
  if (attempts >= MAX_RETRIES) {
    attempts = 0;
    console.error('giving up after retries:', ctx.execution?.error?.message);
    return;
  }
  attempts++;
  const delay = 1000 * 2 ** attempts; // exponential backoff
  console.warn(`retry ${attempts} in ${delay}ms`);
  setTimeout(() => task.execute().catch(() => {}), delay);
});

task.on('execution:finished', () => {
  attempts = 0; // reset after a clean run
});
```

## Run exactly once

Set `maxExecutions: 1` and the task destroys itself after a single run. Combine with `execute()` for an immediate one-shot.

```js
import cron from 'node-cron';

// Runs once at the next minute boundary, then self-destructs.
cron.schedule('* * * * *', () => {
  console.log('one-time job');
}, {
  maxExecutions: 1,
});
```

## Inspect everything that's scheduled

`getTasks()` returns every registered task, handy for a status endpoint or dashboard.

```js
import cron from 'node-cron';

function listTasks() {
  return [...cron.getTasks().values()].map((task) => ({
    id: task.id,
    name: task.name,
    status: task.getStatus(),
    nextRun: task.getNextRun(),
  }));
}

console.table(listTasks());
```

## Graceful shutdown

Stop and destroy every task when the process is terminating. `destroy()` is async for background tasks, so await them all.

```js
import cron from 'node-cron';

async function shutdown() {
  await Promise.all(
    [...cron.getTasks().values()].map((task) => task.destroy())
  );
  process.exit(0);
}

process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);
```

## NestJS: a scheduled job you can also trigger on demand

With [`@node-cron/nestjs`](/nestjs) you schedule with the familiar decorators and still get node-cron's task API. Here a job runs every 30 seconds, and an endpoint triggers it off-schedule and reports when it's next due, using `SchedulerRegistry`.

```ts
// tasks.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { Cron, CronExpression } from '@node-cron/nestjs';

@Injectable()
export class TasksService {
  private readonly logger = new Logger(TasksService.name);

  @Cron(CronExpression.EVERY_30_SECONDS, { name: 'sync' })
  sync() {
    this.logger.log('syncing…');
  }
}
```

```ts
// sync.controller.ts
import { Controller, Post, Get } from '@nestjs/common';
import { SchedulerRegistry } from '@node-cron/nestjs';

@Controller('sync')
export class SyncController {
  constructor(private readonly registry: SchedulerRegistry) {}

  @Post() // run it now, without waiting for the schedule
  runNow() {
    return this.registry.getCronJob('sync').execute();
  }

  @Get('next')
  next() {
    return { nextRun: this.registry.getCronJob('sync').getNextRun() };
  }
}
```

For a job that should run on only one instance across a fleet, add `distributed: true` and a coordinator, see the [NestJS guide](/nestjs#distributed-scheduling).

## Fastify: scheduled jobs as a plugin

With [`@node-cron/fastify`](/fastify) you declare jobs when registering the plugin (they start on `onReady`, stop on `onClose`) and can schedule more imperatively from a route via `fastify.scheduler`.

```ts
import Fastify from 'fastify';
import { fastifyNodeCron } from '@node-cron/fastify';

const app = Fastify();

await app.register(fastifyNodeCron, {
  tasks: [
    { cron: '0 3 * * *', name: 'nightly-backup', run: () => runBackup() },
  ],
});

// schedule on demand, and inspect via the decorator
app.post('/reports/enable', async () => {
  app.scheduler.schedule('*/5 * * * *', () => sendReport(), { name: 'report' });
  return { nextRun: app.scheduler.getTaskByName('report')?.getNextRun() };
});

await app.listen({ port: 3000 });
```

## Next steps

* [API Reference](/api-reference): every function in the module.
* [Events & Observability](/event-listening): the events these recipes hook into.

---

---
url: /prevent-overlapping-cron-jobs.md
description: >-
  Prevent duplicate cron executions when a task runs longer than its interval.
  One option, no external locking, built into node-cron.
---

# How to Prevent Overlapping Cron Jobs in Node.js

A cron job scheduled to run every minute takes 90 seconds to finish. Now two copies are running at once: the first is still going, and the second just started. This is an overlapping execution, and it causes duplicate work, race conditions, and data corruption.

## The problem

Without overlap prevention, a scheduler fires on every tick regardless of whether the previous run finished:

```
minute 1: task starts ──────────────────────── still running
minute 2:               task starts (overlap!) ──────────
minute 3:                              task starts (overlap!) ───
```

## The solution: `noOverlap`

node-cron has built-in overlap prevention. Set `noOverlap: true` and a tick that fires while the previous run is still active is skipped instead of stacked:

```js
import cron from 'node-cron';

cron.schedule('* * * * *', async () => {
  await longRunningJob();
}, {
  noOverlap: true,
});
```

```
minute 1: task starts ──────────────────────── finishes
minute 2:               (skipped, previous still running)
minute 3:                                       task starts ───
```

No external locking, no Redis, no database. It works in-process with zero configuration beyond the flag.

## Detecting skipped runs

When a run is skipped due to overlap, the task emits an `execution:overlap` event. Use it for logging, metrics, or alerting:

```js
const task = cron.schedule('* * * * *', async () => {
  await longRunningJob();
}, {
  noOverlap: true,
});

task.on('execution:overlap', () => {
  console.warn('Skipped: previous execution still running');
});
```

## Combining with other features

`noOverlap` works with every other node-cron feature:

### With background tasks

```js
cron.schedule('*/5 * * * *', './tasks/heavy-sync.js', {
  noOverlap: true,
});
```

The job runs in an isolated forked process, and the scheduler still tracks whether it is active.

### With distributed coordination

```js
cron.schedule('0 * * * *', syncInventory, {
  name: 'sync-inventory',
  noOverlap: true,
  distributed: true,
});
```

Only one instance in the fleet runs each fire, and within that instance, overlapping runs are prevented.

### With events and observability

```js
const task = cron.schedule('*/30 * * * * *', processQueue, {
  noOverlap: true,
});

task.on('execution:started', () => console.log('started'));
task.on('execution:finished', (ctx) => console.log('done:', ctx.execution?.result));
task.on('execution:failed', (ctx) => console.error('failed:', ctx.execution?.error));
task.on('execution:overlap', () => console.warn('skipped: still running'));
```

## When overlap prevention is not enough

`noOverlap` prevents concurrent executions of the same task within a single process (or a single instance when combined with `distributed`). For scenarios that need more:

* **Cross-process locking without node-cron's distributed mode**: use a Redis lock or database advisory lock directly.
* **Durable job queues with retries**: use [BullMQ](https://bullmq.io) or [Sidequest](https://sidequestjs.com), which persist jobs to a backend and handle retries, priorities, and deduplication.
* **Exactly-once execution guarantees**: use a transactional queue or workflow engine.

## Next steps

* [Scheduling Options](/scheduling-options): all options including `noOverlap`, `maxExecutions`, and `maxRandomDelay`.
* [Events & Observability](/event-listening): the full list of lifecycle events.
* [How to run cron jobs across multiple servers](/run-cron-jobs-across-multiple-servers): coordinate tasks across a fleet.

---

---
url: /run-cron-jobs-across-multiple-servers.md
description: >-
  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 Cron Jobs Across Multiple Servers

You deploy three replicas of your Node.js app behind a load balancer. All three have the same code, the same schedule, and the same cron job. At 3 a.m., the nightly backup runs three times instead of once.

This happens in every multi-instance setup: PM2 cluster mode, Kubernetes Deployments, blue/green rollouts, auto-scaling groups. The scheduler doesn't know about other copies of itself.

## The problem

```
instance A: 0 3 * * * → runs backup
instance B: 0 3 * * * → runs backup (duplicate)
instance C: 0 3 * * * → runs backup (duplicate)
```

## The solution: `distributed: true`

node-cron has built-in distributed coordination. Set `distributed: true` and only one instance executes each scheduled fire:

```js
import cron from 'node-cron';

cron.schedule('0 3 * * *', runNightlyBackup, {
  name: 'nightly-backup',
  distributed: true,
});
```

```
instance A: 0 3 * * * → runs backup ✓
instance B: 0 3 * * * → skipped (not elected)
instance C: 0 3 * * * → skipped (not elected)
```

Two things are required:

* A **`name`** for the task (it forms the coordination key shared across instances)
* A way to decide which instance runs: the default uses an **env-var flag**, or you can plug in a **Redis coordinator** for high availability

## Option 1: Designated runner (env-var)

The simplest setup. Designate one instance as the runner:

```bash
# instance A (the runner)
NODE_CRON_RUN=true node app.js

# instances B, C, D
NODE_CRON_RUN=false node app.js
```

This works well when your orchestrator already decides which pod is special: a StatefulSet, a single-replica Deployment, a dedicated worker dyno.

If `NODE_CRON_RUN` is unset, node-cron throws at schedule time (on startup, not silently at 3 a.m.), so a misconfigured deploy fails loudly.

::: warning Trade-off
The env-var default is a single designated runner. If instance A is down at 3 a.m., the backup doesn't run. For high availability, use a coordinator.
:::

## Option 2: Redis coordinator (high availability)

With a Redis coordinator, every replica races for each fire, exactly one wins, and if the winner is down another takes over:

```bash
npm install @node-cron/redis-coordinator
```

```js
import { createClient } from 'redis';
import cron, { setRunCoordinator } from 'node-cron';
import { RedisLockCoordinator } from '@node-cron/redis-coordinator';

const redis = createClient();
await redis.connect();

setRunCoordinator(new RedisLockCoordinator(redis));

cron.schedule('0 3 * * *', runNightlyBackup, {
  name: 'nightly-backup',
  distributed: true,
  distributedLease: 5 * 60_000,
});
```

No special instance needed. Works with both [ioredis](https://github.com/redis/ioredis) and [node-redis](https://github.com/redis/node-redis) v4.

## Knowing when an instance skips

When an instance is not elected to run, it emits `execution:skipped`:

```js
task.on('execution:skipped', (ctx) => {
  if (ctx.reason === 'coordinator-error') {
    alert('coordination backend is down', ctx);
  }
});
```

| Reason | Meaning |
| --- | --- |
| `not-elected` | Healthy. Another instance ran this fire. |
| `coordinator-error` | The coordinator failed (e.g. Redis down). The fire may not have run anywhere. Alert on this. |

## Custom coordinators

The Redis coordinator is one implementation of the `RunCoordinator` interface. You can back coordination with anything your fleet shares:

```ts
interface RunCoordinator {
  shouldRun(key: string, ttlMs: number): boolean | Promise<boolean>;
  onComplete?(key: string): void | Promise<void>;
}
```

Postgres, etcd, DynamoDB, or any distributed lock mechanism works.

## Combining with other features

### With overlap prevention

```js
cron.schedule('0 * * * *', syncInventory, {
  name: 'sync-inventory',
  distributed: true,
  noOverlap: true,
});
```

One instance runs each fire, and within that instance, overlapping runs are prevented.

### With background tasks

```js
setRunCoordinator(new RedisLockCoordinator(redis));

cron.schedule('0 3 * * *', './tasks/backup.js', {
  name: 'nightly-backup',
  distributed: true,
});
```

The forked daemon asks the parent over IPC, and the parent runs the coordinator. No extra configuration.

## When distributed coordination is not enough

node-cron's distributed mode guarantees no concurrent execution across instances when clocks are in sync. It is not a hard exactly-once: under a crash-and-retry or large clock skew, a fire could run more than once. Treat distributed tasks as idempotent.

For stronger guarantees:

* **Durable job queues**: [BullMQ](https://bullmq.io), [Sidequest](https://sidequestjs.com)
* **Workflow orchestration**: [Temporal](https://temporal.io), [Inngest](https://inngest.com)

## Next steps

* [Distributed Coordination](/distributed-coordination): the full reference, including lease tuning and clock skew.
* [How to prevent overlapping cron jobs](/prevent-overlapping-cron-jobs): overlap prevention within a single instance.
* [How to run background jobs in Node.js](/run-background-jobs-in-nodejs): isolate heavy work in forked processes.

---

---
url: /run-background-jobs-in-nodejs.md
description: >-
  Run scheduled jobs in isolated forked processes so heavy work never blocks
  your main event loop. Built into node-cron, no external queue needed.
---

# How to Run Background Jobs in Node.js

A CPU-heavy cron job blocks the event loop. While it runs, your HTTP server stops responding, WebSocket connections drop, and other scheduled tasks miss their window. The job finishes, but the collateral damage is already done.

## The problem

Node.js runs JavaScript on a single thread. When a scheduled task does heavy computation, file I/O, or a long synchronous operation, everything else in the process waits:

```
main thread: ──── cron fires ──── heavy job (3s) ──── blocked ────
                                  ↑ HTTP requests queue up
                                  ↑ other cron tasks miss their tick
                                  ↑ WebSocket pings time out
```

## The solution: background tasks

node-cron can run any scheduled job in an isolated forked process. Pass a **file path** instead of a function, and the job runs in its own process, completely isolated from your main event loop:

```js
// tasks/generate-report.js
export function task() {
  // This runs in a separate process.
  // Heavy computation here won't block your HTTP server.
  return generateMonthlyReport();
}
```

```js
// app.js
import cron from 'node-cron';

cron.schedule('0 2 1 * *', './tasks/generate-report.js');
```

```
main thread: ──── cron fires ──── continues serving requests ────
forked process:   ──── heavy job (3s) ──── done ────
```

Your HTTP server keeps responding. Other cron tasks fire on time. The background job runs to completion in its own process.

## Same interface, same features

A background task implements the same `ScheduledTask` interface as an inline task. The only difference: control methods return Promises because they cross a process boundary.

```js
const task = cron.schedule('0 2 * * *', './tasks/report.js');

await task.stop();      // terminates the child process
await task.start();     // re-forks and resumes
await task.destroy();   // kills the process and removes the task

task.getStatus();       // 'idle', 'running', etc.
task.getNextRun();      // next scheduled Date
```

## Events and observability

Background tasks emit the same lifecycle events, relayed from the worker to the parent:

```js
const task = cron.schedule('0 2 * * *', './tasks/report.js');

task.on('execution:started', () => console.log('report generation started'));
task.on('execution:finished', (ctx) => console.log('done:', ctx.execution?.result));
task.on('execution:failed', (ctx) => console.error('failed:', ctx.execution?.error));
```

## Manual execution

Trigger a background task immediately with `execute()`:

```js
const task = cron.schedule('0 2 * * *', './tasks/report.js');

const result = await task.execute();
```

Guard against a worker that never reports back with `executeTimeout`:

```js
const task = cron.schedule('0 2 * * *', './tasks/report.js', {
  executeTimeout: 60_000,
});
```

## Combining with other features

### With overlap prevention

```js
cron.schedule('*/5 * * * *', './tasks/sync.js', {
  noOverlap: true,
});
```

The scheduler tracks whether the forked process is still active and skips the next tick if it is.

### With distributed coordination

```js
import { setRunCoordinator } from 'node-cron';
import { RedisLockCoordinator } from '@node-cron/redis-coordinator';

setRunCoordinator(new RedisLockCoordinator(redis));

cron.schedule('0 3 * * *', './tasks/backup.js', {
  name: 'nightly-backup',
  distributed: true,
});
```

Coordination happens in the parent process over IPC. No extra configuration needed.

### With timezones

```js
cron.schedule('0 3 * * *', './tasks/backup.js', {
  timezone: 'America/Sao_Paulo',
});
```

## Writing a task file

A task file exports a `task` function. It receives a `TaskContext` with scheduling metadata:

```js
// tasks/cleanup.js
export function task(ctx) {
  console.log('scheduled for:', ctx.dateLocalIso);
  return cleanupOldRecords();
}
```

The function can be sync or async. Its return value is available in the `execution:finished` event and through `lastRun()`.

## When background tasks are not enough

Background tasks isolate work from your main event loop, but the job still runs inside your Node.js application lifecycle. For scenarios that need more:

* **Persistent job queues with retries**: [BullMQ](https://bullmq.io) or [Sidequest](https://sidequestjs.com) persist jobs to Redis/database and retry on failure.
* **Worker pools**: for CPU-bound work that needs multiple parallel workers, consider [piscina](https://github.com/piscinajs/piscina) or [workerpool](https://github.com/josdejong/workerpool).
* **External job runners**: for jobs that outlive your process, use a managed scheduler like AWS EventBridge or GCP Cloud Scheduler.

## Next steps

* [Background Tasks](/background-tasks): the full reference, including `startTimeout` and limitations.
* [How to prevent overlapping cron jobs](/prevent-overlapping-cron-jobs): prevent duplicate executions.
* [How to run cron jobs across multiple servers](/run-cron-jobs-across-multiple-servers): coordinate across instances.

---

---
url: /api-reference.md
description: >-
  Complete reference for the node-cron module (schedule, createTask, validate,
  getTasks, getTask, and setLogger), with parameters, return types, and
  examples.
---

# API Reference

This page documents every public function exported by the `node-cron` module. For conceptual guides, follow the links into [Task Lifecycle](/task-lifecycle), [Scheduling Options](/scheduling-options), and [Events](/event-listening).

```js
import cron, {
  schedule,
  createTask,
  validate,
  validateDetailed,
  parse,
  getTasks,
  getTask,
  setLogger,
  setRunCoordinator,
  shutdown,
} from 'node-cron';
```

Both the default export (`cron.schedule(...)`) and named exports (`schedule(...)`) are available.

## `schedule(expression, func, options?)`

Creates a task and **starts it immediately**. Returns a [`ScheduledTask`](/task-lifecycle#the-scheduledtask-interface).

### Parameters

| Name         | Type                   | Description                                                                                                   |
| ------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `expression` | `string`               | A valid [cron expression](/cron-syntax) (e.g. `"0 0 * * *"` for daily at midnight).                          |
| `func`       | `Function \| string`   | A function to run, **or** a path to a module exporting a `task` function. A path creates a [Background Task](/background-tasks). |
| `options`    | `Options` *(optional)* | Execution options. See [Scheduling Options](/scheduling-options).                                            |

### Options

```ts
type Options = {
  name?: string;                  // human-readable identifier
  timezone?: string;              // e.g. "America/New_York"
  noOverlap?: boolean;            // skip a run if the previous one is still going
  maxExecutions?: number;         // destroy the task after N runs
  maxRandomDelay?: number;        // jitter, in ms, added before each run
  logger?: Logger;                // per-task logger (not for background tasks)
  suppressMissedWarning?: boolean // silence the "missed execution" warning
  missedExecutionTolerance?: number // ms a late run may still execute (default 1000)
  distributed?: boolean;          // run on one instance per fire across a fleet
  runCoordinator?: RunCoordinator;// per-task coordinator (overrides the global one)
  distributedLease?: number;        // lease ms for lease-based coordinators (default 30000)
  unref?: boolean;                // don't keep the process alive for this task's timer
};
```

Background tasks accept two extra options, `executeTimeout` and `startTimeout`, documented in [Background Tasks](/background-tasks#manual-execution-and-executetimeout).

See [Scheduling Options](/scheduling-options) for details and examples.

### Returns

A [`ScheduledTask`](/task-lifecycle) with control methods:

```js
import cron from 'node-cron';

const task = cron.schedule('* * * * *', () => {
  console.log('Running every minute');
});

task.stop();    // pause the task
task.start();   // start or resume it
task.destroy(); // remove it permanently
```

> 🛈 For **inline** tasks these methods are synchronous (`void`); for **background** tasks they return a `Promise`. See [Task Lifecycle](/task-lifecycle#inline-vs-background-sync-vs-async).

## `createTask(expression, func, options?)`

Same as `schedule`, but **does not start** the task; it's returned in the `stopped` state. Useful when you need to attach [event listeners](/event-listening) first, start conditionally, or control timing in tests.

```js
import cron from 'node-cron';

const task = cron.createTask('0 * * * *', () => {
  console.log('Running every hour');
});

task.start();
```

## `validate(expression)`

Returns `true` if the cron expression is syntactically valid, `false` otherwise.

```js
import cron from 'node-cron';

cron.validate('0 12 * * *'); // true
cron.validate('invalid');    // false
```

## `validateDetailed(expression)`

Like `validate`, but instead of a boolean returns a structured result describing **every** problem (which field, the offending value, and why). Useful for tooling, editors, and richer error messages.

```ts
type CronFieldError = { field: string; value?: string; message: string };
type DetailedValidation = {
  valid: boolean;
  fields?: ParsedFields;   // present only when valid
  errors: CronFieldError[];
};
```

```js
import { validateDetailed } from 'node-cron';

validateDetailed('0 12 * * *');
// { valid: true, errors: [], fields: { second: [0], minute: [0], hour: [12], ... } }

validateDetailed('99 12 * * 9');
// {
//   valid: false,
//   errors: [
//     { field: 'minute',    value: '99', message: '99 is a invalid expression for minute' },
//     { field: 'dayOfWeek', value: '9',  message: '9 is a invalid expression for week day' },
//   ]
// }
```

It reports **every** bad field at once (not just the first). See [Cron Syntax](/cron-syntax#validating-expressions).

## `parse(expression)`

Parses a cron expression into its decomposed, expanded fields, or **throws** an `Error` describing the first invalid field.

```ts
type ParsedFields = {
  second: number[];
  minute: number[];
  hour: number[];
  dayOfMonth: (number | string)[];
  month: number[];
  dayOfWeek: (number | string)[];
};
```

```js
import { parse } from 'node-cron';

parse('0 12 * * 1-5');
// { second: [0], minute: [0], hour: [12], dayOfMonth: [1, …, 31], month: [1, …, 12], dayOfWeek: [1, 2, 3, 4, 5] }

parse('0 99 * * *'); // throws: 99 is a invalid expression for hour
```

Use `parse` when you want the structured fields (or a thrown error); use [`validate`](#validate-expression) for a boolean and [`validateDetailed`](#validatedetailed-expression) for a non-throwing list of problems.

## `getTasks()`

Returns a `Map<string, ScheduledTask>` of every task currently registered by node-cron, keyed by task id. Tasks created with `schedule` or `createTask` are registered automatically, and a destroyed task removes itself from the registry. Useful for inspection, dashboards, or shutting everything down.

```js
import cron from 'node-cron';

const task = cron.schedule('* * * * *', () => {
  console.log('Running every minute');
});

const tasks = cron.getTasks();

console.log(tasks.has(task.id));          // true
console.log(tasks.get(task.id) === task); // true
```

You can also iterate the map directly:

```js
import cron from 'node-cron';

for (const [id, task] of cron.getTasks()) {
  console.log(id, task.name, task.getStatus());
}
```

## `getTask(id)`

Returns the registered [`ScheduledTask`](/task-lifecycle) with the given id, or `undefined` when no task exists for that id.

```js
import cron from 'node-cron';

const task = cron.schedule('* * * * *', () => {});

const sameTask = cron.getTask(task.id); // === task
sameTask?.stop();
```

## `setLogger(logger)`

Replaces the global logger node-cron uses for its internal messages (such as the missed-execution warning), routing them through your own logger.

```js
import { setLogger } from 'node-cron';

setLogger({
  info:  (msg) => myLogger.info(msg),
  warn:  (msg) => myLogger.warn(msg),
  error: (msg, err) => myLogger.error(err ?? msg),
  debug: (msg) => myLogger.debug(msg),
});
```

The argument is any object implementing the `Logger` interface (`info`, `warn`, `error`, `debug`). See the [Logging guide](/logging) for the full interface, per-task loggers, winston/pino adapters, and the missed-execution warning.

## `setRunCoordinator(coordinator)`

Sets the process-wide [run coordinator](/distributed-coordination) used by tasks scheduled with `distributed: true`. This is the high-availability path: any instance can run a fire, only one wins. Without it, `distributed` tasks fall back to the `NODE_CRON_RUN` env-var default (a single designated runner).

```js
import { setRunCoordinator } from 'node-cron';
import { RedisLockCoordinator } from '@node-cron/redis-coordinator';

setRunCoordinator(new RedisLockCoordinator(redis));
```

The argument is any object implementing the `RunCoordinator` interface:

```ts
interface RunCoordinator {
  shouldRun(key: string, ttlMs: number): boolean | Promise<boolean>;
  onComplete?(key: string): void | Promise<void>;
}
```

Pass `undefined` to clear it. A per-task coordinator can be set via the [`runCoordinator`](/scheduling-options) option. See [Distributed Coordination](/distributed-coordination) for the full guide.

## `shutdown(timeout?)`

Gracefully tears down **every** registered task: stops each one, waits for any in-flight run to settle (up to `timeout`), then destroys them all and clears the registry. Returns a `Promise` that resolves once teardown is complete. Call it from a signal handler so a redeploy or Ctrl-C doesn't cut a running job in half.

| Name      | Type     | Default | Description                                                        |
| --------- | -------- | ------- | ------------------------------------------------------------------ |
| `timeout` | `number` | `5000`  | Max time (ms) to wait for busy tasks to finish before destroying them. Tasks that are idle don't wait. |

```js
import { shutdown } from 'node-cron';

async function stop() {
  await shutdown(10_000); // give running jobs up to 10s to finish
  process.exit(0);
}

process.once('SIGTERM', stop);
process.once('SIGINT', stop);
```

* Only tasks that are actually running when `shutdown` is called are awaited; the timeout is a ceiling, not a fixed delay.
* After it resolves, every task is `destroyed` and [`getTasks()`](#gettasks) is empty. Create new tasks if the process keeps running.
* Errors thrown while stopping or destroying an individual task are routed to the [logger](/logging), not rethrown, so one bad task can't abort the whole shutdown.

## Next steps

* [Task Lifecycle & Status](/task-lifecycle): what the returned task can do.
* [Migrating from v3](/migrating-from-v3): if you're upgrading an existing project.

---

---
url: /migrating-from-v2.md
description: >-
  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.
---

# Migration Guide: node-cron v2 to v3

`node-cron` v3 kept the same `schedule` / `validate` core as v2, but reshaped the task object and added background tasks, a task registry, and an event API.

This guide compares the last v2 release (**v2.0.3**) with v3 (**v3.0.x**). It covers the breaking changes you hit when bumping from v2 to v3. If you are already on v3 and heading to v4, see [Migrating from v3](/migrating-from-v3).

::: tip Already on the latest?
v2 is old. If you are jumping straight from v2 to **v4**, read this page first for the v2 to v3 changes, then [Migrating from v3](/migrating-from-v3) for v3 to v4. Some methods removed here (`getStatus`, `destroy`) come back in v4.
:::

Both v2 and v3 are CommonJS and run on Node.js >= 6, so there are no runtime or import changes. The import stays the same:

```js
const cron = require('node-cron');
```

## Breaking changes

### 1. `task.getStatus()` and `task.destroy()` were removed

In v2 the scheduled task exposed `start()`, `stop()`, `getStatus()`, and `destroy()`. In v3 the task only exposes `start()`, `stop()`, and `now()`. The `getStatus()` and `destroy()` methods are gone.

```js
// v2
const task = cron.schedule('* * * * *', () => {});
task.getStatus(); // 'scheduled' | 'running' | 'stoped' | 'destroyed' | 'failed'
task.destroy();

// v3: these methods no longer exist
const task = cron.schedule('* * * * *', () => {});
task.stop(); // use stop() instead of destroy()
```

If you relied on `getStatus()`, track state yourself from the new [`task-done`](#_4-task-events-new) event, or upgrade to [v4](/migrating-from-v3), where `getStatus()` and `destroy()` return with a richer status model.

### 2. The boolean third argument is gone

v2 accepted a boolean as the third argument to control whether the task started immediately (the old `immediateStart`), and already logged a deprecation warning for it. v3 removes it: the third argument must be an options object.

```js
// v2 (deprecated, warned)
cron.schedule('* * * * *', () => {}, false);

// v3
cron.schedule('* * * * *', () => {}, { scheduled: false });
```

`scheduled: false` creates the task without starting it. Call `task.start()` when you are ready.

## New in v3

These are additive, so they do not break v2 code, but they are the reason to upgrade.

### 3. Background tasks

In v3, passing a **file path string** instead of a function runs the task in a separate forked process. v2 only supported inline functions.

```js
// v3 only: runs ./tasks/job.js in a forked process
cron.schedule('0 0 * * *', './tasks/job.js', {
  timezone: 'America/Sao_Paulo'
});
```

### 4. Task events (new)

In v2 the scheduled task had no public event API. In v3 the task extends Node's `EventEmitter` and emits a `task-done` event after each run, so you can react to completions:

```js
const task = cron.schedule('* * * * *', () => {});

task.on('task-done', (result) => {
  console.log('Run finished:', result);
});
```

::: tip Heading to v4 next?
v4 replaces `task-done` with a richer set of `execution:*` and `task:*` events and removes the `EventEmitter` base class. See [Migrating from v3](/migrating-from-v3).
:::

### 5. `cron.getTasks()`

v3 keeps a registry of every scheduled task and exposes it through `cron.getTasks()`, which returns a `Map` of the live tasks. v2 had no such API.

```js
cron.schedule('* * * * *', () => {});

for (const [name, task] of cron.getTasks()) {
  console.log(name, task);
}
```

### 6. New options

v3 adds three options to `schedule`:

* `name`: a name for the task (also used as the `getTasks()` key; defaults to a generated id).
* `runOnInit`: run the task once immediately when it is scheduled.
* `recoverMissedExecutions`: replay runs that were missed while the event loop was blocked.

```js
cron.schedule('* * * * *', () => {}, {
  name: 'heartbeat',
  runOnInit: true,
  timezone: 'America/Sao_Paulo'
});
```

## Quick checklist

* \[ ] Replace `task.getStatus()` and `task.destroy()`: use `task.stop()`, or upgrade to [v4](/migrating-from-v3) for the full status API.
* \[ ] Change any `schedule(expr, fn, false)` boolean argument to `schedule(expr, fn, { scheduled: false })`.
* \[ ] Optionally adopt background tasks, the `task-done` event, `getTasks()`, and the new options.

Once on v3, see [Migrating from v3](/migrating-from-v3) to continue to v4.

---

---
url: /migrating-from-v3.md
description: >-
  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.
---

# Migration Guide: node-cron v3 to v4

`node-cron` v4 is a significant update, both in internal optimizations and in the move to TypeScript. It improves scheduling performance and provides a more flexible API for handling scheduled tasks.

This guide compares the last v3 release (**v3.0.3**) with the current v4 line (**v4.5.x**), so it covers everything you hit when you bump the major.

## Before you start: new requirements

Two environment-level changes affect every project, regardless of which APIs you use:

* **Node.js >= 20.** v3 supported Node as old as 6. v4 requires Node.js 20 or newer. Upgrade your runtime before bumping the package.
* **ESM-first, with CommonJS still supported.** v4 ships as a dual package (`"type": "module"`) with both ESM and CommonJS builds plus type declarations. Both of these keep working:

```js
// ESM (default export)
import cron from 'node-cron';

// CommonJS
const cron = require('node-cron');
```

v4 also exposes **named exports**, which v3 did not:

```js
import { schedule, createTask, validate, getTasks } from 'node-cron';
```

## Internal changes

* **Smarter scheduling.** v3 checked the cron expression every second. v4 dynamically calculates the delay until the next matching time and sleeps until then, instead of waking up once per second. For a task that runs every 5 minutes, the scheduler no longer does ~300 needless checks between runs. This lowers CPU overhead.
* **TypeScript rewrite.** v4 is written in TypeScript and ships type declarations, so you get type safety and richer editor support out of the box.

## Breaking changes and how to migrate

### 1. Task creation and options

#### v3

In v3 you used the `scheduled` and `runOnInit` options to control startup behavior.

```js
const task = cron.schedule('* * * * *', async () => {
  console.log('Running every minute');
}, {
  scheduled: true,
  runOnInit: true,
  timezone: 'America/Sao_Paulo'
});
```

#### v4

The `scheduled` and `runOnInit` options are removed. By default, a task created with `cron.schedule` is started immediately. To run the function once right after scheduling, call `task.execute()`:

```js
const task = cron.schedule('* * * * *', async () => {
  console.log('Running every minute');
}, {
  timezone: 'America/Sao_Paulo'
});

// Immediately run the task once, in addition to its schedule.
task.execute();
```

If you need a task that does **not** start on creation (the old `scheduled: false`), use `cron.createTask` and start it yourself:

```js
const task = cron.createTask('* * * * *', async () => {
  console.log('This task is manually started');
}, {
  noOverlap: true
});

// The task will not run until start() is called.
task.start();
```

### 2. Task options (`Options` vs `CronScheduleOptions`)

#### v3

```js
/**
 * @typedef {Object} CronScheduleOptions
 * @prop {boolean} [scheduled] whether the task is started when created.
 * @prop {boolean} [runOnInit] run the task once when scheduling.
 * @prop {boolean} [recoverMissedExecutions] replay runs missed while blocked.
 * @prop {string}  [timezone] the timezone to execute the task in.
 * @prop {string}  [name] a name for the task.
 */
```

#### v4

Options are streamlined into a single `Options` type with updated field names. The v3 fields `scheduled`, `runOnInit`, and `recoverMissedExecutions` are all **removed**.

```ts
export type Options = {
  name?: string;
  timezone?: string;
  noOverlap?: boolean;
  maxExecutions?: number;
  maxRandomDelay?: number;
  logger?: Logger;
  suppressMissedWarning?: boolean;
};
```

Field reference:

* `name`: A human-readable identifier for the task (useful for debugging or logging).
* `timezone`: The timezone in which the cron expression is interpreted.
* `noOverlap`: Prevents a run from starting while a previous run is still going.
* `maxExecutions`: Limits the number of executions before the task is automatically destroyed.
* `maxRandomDelay`: Adds random jitter (ms) before each run.
* `logger`: A per-task [logger](/logging) (not supported for background tasks).
* `suppressMissedWarning`: Silences the missed-execution warning.

See [Scheduling Options](/scheduling-options) for the full reference.

#### What happened to `recoverMissedExecutions`?

v3 could replay runs that were missed while the event loop was blocked. v4 removes that option. Instead, a missed run emits an [`execution:missed`](/event-listening) event, and node-cron logs a one-time warning you can silence with `suppressMissedWarning`. v4 does not replay missed runs automatically; if you need that behavior, handle the `execution:missed` event yourself. See [Logging](/logging#suppressing-the-missed-execution-warning).

### 3. Task methods

The task object returned by `schedule` and `createTask` changed shape.

| v3 | v4 | Notes |
|---|---|---|
| `task.now()` | `task.execute()` | Manually run the task once. Now returns a `Promise`. |
| `task.start()` | `task.start()` | Unchanged. |
| `task.stop()` | `task.stop()` | Unchanged. |
| (none) | `task.destroy()` | Stop permanently and remove from the registry. |
| (none) | `task.getStatus()` | Returns `'stopped'`, `'idle'`, `'running'`, or `'destroyed'`. |
| (none) | `task.getNextRun()` / `task.getNextRuns(n)` | Next fire time(s). |
| (none) | `task.lastRun()` | The last run's date, result, or error. |

The biggest rename to watch for: **`task.now()` is now `task.execute()`**. Search your codebase for `.now(` calls on tasks.

### 4. Task events

This is the largest API change, and the v3-to-v4 mapping is not one-to-one.

#### v3

v3's `ScheduledTask` extended Node's `EventEmitter`. The one public event was **`task-done`**, emitted after each run:

```js
const task = cron.schedule('* * * * *', async () => {
  console.log('Running every minute');
});

task.on('task-done', (result) => {
  console.log('Run finished:', result);
});
```

#### v4

`ScheduledTask` no longer extends `EventEmitter`. It exposes `on`, `once`, and `off` directly, and every listener receives a [`TaskContext`](/event-listening) with runtime metadata instead of a bare value. Event names now use a `namespace:event` convention and are split into two families:

**Lifecycle events** (the task itself):

* `task:started`
* `task:stopped`
* `task:destroyed`

**Execution events** (a single run of the task):

* `execution:started`
* `execution:finished`
* `execution:failed`
* `execution:missed`
* `execution:overlap`
* `execution:maxReached`
* `execution:skipped`

The old `task-done` maps to the execution events: a successful run is now `execution:finished`, and a failure is `execution:failed`.

```js
const task = cron.schedule('* * * * *', async () => {
  console.log('Running every minute');
});

// v3: task.on('task-done', result => ...)
task.on('execution:finished', (context) => {
  console.log('Run finished at', context.date, context.execution?.result);
});

task.on('execution:failed', (context) => {
  console.error('Run failed:', context.execution?.error);
});
```

Each listener receives a `TaskContext`:

```ts
type TaskContext = {
  date: Date;            // the scheduled time this fired for
  dateLocalIso: string;  // that time as a local ISO 8601 string
  triggeredAt: Date;     // when the listener was actually invoked
  task?: ScheduledTask;  // the task that emitted the event
  execution?: Execution; // run details, present for execution:* events
};
```

See the [Events & Observability guide](/event-listening) for the full event and `TaskContext` reference.

### 5. Background tasks (task files)

Passing a file path instead of a function still creates a background task that runs in a forked process:

```js
cron.schedule('0 0 * * *', './tasks/daily-backup.js', {
  timezone: 'America/New_York'
});
```

What changed:

* Background tasks now implement the **same `ScheduledTask` interface** as inline tasks (`start`, `stop`, `destroy`, `execute`, events). The v3-only methods `task.pid()` and `task.isRunning()` are gone; use `task.getStatus()` instead.
* The `logger` option is **not supported** for background tasks, since the task runs in a separate process.

### 6. Registry lookups

`cron.getTasks()` still returns a `Map` of the live tasks, and v4 adds `cron.getTask(id)` to fetch one by id. The map is now keyed by the task `id` rather than the v3 task name, so update any code that looked tasks up by key.

## Quick checklist

* \[ ] Upgrade to Node.js 20+.
* \[ ] Remove `scheduled`, `runOnInit`, and `recoverMissedExecutions` from your options.
* \[ ] Replace `task.now()` with `task.execute()`.
* \[ ] For tasks that should start stopped, switch `schedule(..., { scheduled: false })` to `createTask(...)` then `.start()`.
* \[ ] Migrate `task.on('task-done', ...)` to `execution:finished` / `execution:failed`, and update listeners to read from `TaskContext`.
* \[ ] Replace any `task.pid()` / `task.isRunning()` calls on background tasks with `task.getStatus()`.
* \[ ] If you relied on missed-run recovery, handle `execution:missed` yourself.

See the [Events & Observability guide](/event-listening) and [Scheduling Options](/scheduling-options) for more detail.

---

---
url: /migrating-from-cron.md
description: >-
  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.
---

# Migrating from the `cron` package

The npm ecosystem has two popular, separately maintained packages with similar names: **`node-cron`** (this project) and **`cron`**. They are not forks or versions of each other, they have different authors and different APIs.

Both are valid choices. If you searched for "node-cron" and landed on the other one, or you are running the `cron` package and want to move to `node-cron`, this page shows how to port your code. Your cron **expressions** carry over unchanged (both support standard syntax with an optional seconds field), only the **API** is different.

## What changes when you move

Moving to `node-cron` changes a few concrete things in how you write the code:

* **No runtime dependencies** — `node-cron` ships zero dependencies.
* **Event-based lifecycle** — `execution:finished`, `execution:failed`, and more, instead of a single `onComplete` callback.
* **Built-in options** for common needs: overlap protection (`noOverlap`), execution caps (`maxExecutions`), and jitter (`maxRandomDelay`).
* **First-class TypeScript types.**

These are differences in shape, not a scorecard. Pick what fits your project.

## Installation

```bash
npm uninstall cron
npm install node-cron
```

## The core difference: constructor vs `schedule`

The `cron` package builds a job with a positional constructor and a boolean to start it. `node-cron` uses a single `schedule` call that starts immediately, plus an options object.

**Before (`cron`):**

```js
const { CronJob } = require('cron');

const job = new CronJob(
  '0 */5 * * * *',           // cronTime
  () => doWork(),            // onTick
  null,                      // onComplete
  true,                      // start
  'America/Sao_Paulo'        // timeZone
);
```

**After (`node-cron`):**

```js
import cron from 'node-cron';

const task = cron.schedule('0 */5 * * * *', () => doWork(), {
  timezone: 'America/Sao_Paulo',
});
```

`cron.schedule(...)` starts the task right away. If you need a task that does **not** start immediately (the `start: false` case), use `createTask` and start it yourself:

```js
const task = cron.createTask('0 */5 * * * *', () => doWork());
// later
task.start();
```

## Option mapping

| `cron` package | `node-cron` | Notes |
| --- | --- | --- |
| `timeZone: 'America/Sao_Paulo'` | `{ timezone: 'America/Sao_Paulo' }` | IANA name, same values. |
| `start` (4th constructor arg) | `cron.schedule` (starts) / `cron.createTask` (manual) | No boolean flag. |
| `onComplete` (3rd arg) | `task.on('execution:finished', ...)` | Event instead of callback. |
| `runOnInit: true` | call the function yourself before scheduling | Removed by design, see below. |
| `utcOffset: -180` | `{ timezone: 'America/Sao_Paulo' }` | Prefer an IANA timezone over a raw offset. |
| `context` (this binding) | use a closure / arrow function | No separate context arg. |
| `unrefTimeout` | not applicable | node-cron manages its own timers. |

## Lifecycle methods

| `cron` package | `node-cron` |
| --- | --- |
| `job.start()` | `task.start()` |
| `job.stop()` | `task.stop()` |
| (no direct equivalent) | `task.destroy()` removes the task permanently |
| `job.running` | `task.getStatus()` → `'stopped' \| 'idle' \| 'running' \| 'destroyed'` |
| `job.nextDate()` | `task.getNextRuns(1)[0]` |
| `job.nextDates(n)` | `task.getNextRuns(n)` |

## Error handling

In the `cron` package an error thrown inside `onTick` surfaces inside the library. In `node-cron`, subscribe to the failure event:

```js
const task = cron.schedule('* * * * *', async () => {
  await mightThrow();
});

task.on('execution:failed', (ctx) => {
  console.error('job failed:', ctx.execution?.error);
});
```

Other lifecycle events you can listen to: `task:started`, `task:stopped`, `task:destroyed`, `execution:started`, `execution:finished`, `execution:missed`, `execution:overlap`, `execution:maxReached`.

## `runOnInit` replacement

The `cron` package can fire once on startup with `runOnInit: true`. `node-cron` does not have this flag, run the work yourself, then schedule it:

```js
async function job() { /* ... */ }

await job();                       // run once on startup
cron.schedule('0 * * * *', job);   // then on schedule
```

## Preventing overlapping runs

If your `onTick` was long-running and you guarded against overlap manually, `node-cron` has it built in:

```js
cron.schedule('* * * * *', longJob, { noOverlap: true });
```

A run is skipped (and an `execution:overlap` event is emitted) if the previous one is still in progress.

## Full before / after example

**Before (`cron`):**

```js
const { CronJob } = require('cron');

const job = new CronJob(
  '0 0 3 * * *',
  async function () {
    try {
      await runBackup();
    } catch (err) {
      console.error(err);
    }
  },
  null,
  true,
  'America/Sao_Paulo'
);
```

**After (`node-cron`):**

```js
import cron from 'node-cron';

const task = cron.schedule('0 0 3 * * *', () => runBackup(), {
  name: 'nightly-backup',
  timezone: 'America/Sao_Paulo',
  noOverlap: true,
});

task.on('execution:failed', (ctx) => console.error(ctx.execution?.error));
```

## Need help?

If something in your `cron` setup does not map cleanly, [open an issue](https://github.com/node-cron/node-cron/issues) and we will help you port it.

---

---
url: /sponsors.md
description: >-
  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.
---

# Help keep node-cron dependable.

node-cron has scheduled jobs in Node.js since 2016. Today it runs in 220,000+ repositories at around 20 million downloads a month, with zero runtime dependencies. It is maintained in the open, for free.

If it is part of your stack, sponsoring is a simple way to help keep it that way. Your support goes to the DST and timezone test suite that keeps jobs firing correctly through clock changes, the lifecycle observability that makes production debugging easier, and the ongoing work of holding the dependency count at zero.

[![npm downloads](https://img.shields.io/npm/dm/node-cron?label=downloads%2Fmonth\&color=2f9d5f)](https://www.npmjs.com/package/node-cron)
[![used by](https://img.shields.io/badge/used%20by-220k%2B%20repos-2f9d5f)](https://github.com/node-cron/node-cron/network/dependents)
[![GitHub stars](https://img.shields.io/github/stars/node-cron/node-cron?color=2f9d5f)](https://github.com/node-cron/node-cron)
[![dependencies](https://img.shields.io/badge/dependencies-0-2f9d5f)](https://www.npmjs.com/package/node-cron?activeTab=dependencies)

## Our sponsors

## What your sponsorship funds

## Tiers

| Tier | Monthly | What you get |
| --- | --- | --- |
| **Gold** | $50 | Large logo at the top of the README, docs, and this page. Visible to developers across 220,000+ dependent repositories. The most visible way to support the project. |
| **Silver** | $25 | Logo in the README and on this page, seen by developers in the 220,000+ repositories that already depend on node-cron. |
| **Bronze** | $10 | Your logo and link on this page. A meaningful presence that helps keep the library tested and at zero dependencies. |
| **Backer** | $5 | Your name and link in the backers list. Every bit adds up to the hours that keep the library tested and at zero dependencies. |

Sponsor through [GitHub Sponsors](https://github.com/sponsors/node-cron) or [Open Collective](https://opencollective.com/node-cron). This page updates automatically from both.

---

---
url: /task-controls.md
description: This page has moved to Task Lifecycle & Status.
---

# Task Controls

> 📦 **This page has moved.** Task controls (`start`, `stop`, `destroy`, `execute`, `getStatus`, and `getNextRun`) are now documented in **[Task Lifecycle & Status](/task-lifecycle)**, alongside the states a task moves through.

Continue to [Task Lifecycle & Status](/task-lifecycle)