cron

library0.0.1jsnpmunverified

The `cron` library for Node.js provides a robust solution for scheduling tasks (functions or external commands) using the familiar cron syntax, with support for second-level precision. The current stable version is 4.4.0, demonstrating active development with regular patch and minor releases, alongside beta releases for upcoming major versions like v5. Key differentiators include its flexibility in defining schedules using cron strings, standard JavaScript `Date` objects, or `Luxon DateTime` objects, comprehensive TypeScript support, and features for managing job lifecycle (start, stop, handling unexpected termination). It is designed for long-running Node.js applications and has evolved through major versions, introducing stricter cron pattern adherence and API refinements.

workflow

npm install cron

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CRON

cron

workflowjavascriptv0.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CronJob

✓ import { CronJob } from 'cron';

✗ const CronJob = require('cron').CronJob;

The primary class for creating and managing scheduled tasks. ESM is the recommended import style; CommonJS can use `const { CronJob } = require('cron');`.

CronTime

✓ import { CronTime } from 'cron';

✗ const CronTime = require('cron').CronTime;

Used for advanced manipulation and parsing of cron time patterns. Typically used internally or for validation.

CronJobParameters

✓ import type { CronJobParameters } from 'cron';

TypeScript type definition for the parameters accepted by the CronJob constructor or `CronJob.from` static method.

Schedules a function to run every second using a cron string and demonstrates basic job creation and immediate start.

import { CronJob } from 'cron'; // This job runs every second, logging a message to the console. // The cronTime pattern '* * * * * *' specifies: second, minute, hour, day of month, month, day of week. const job = new CronJob( '* * * * * *', // cronTime: run every second function () { const now = new Date(); console.log('You will see this message every second:', now.toLocaleTimeString()); }, // onTick: function to execute when the job runs null, // onComplete: function to execute when the job stops (optional) true, // start: boolean to start the job immediately 'America/Los_Angeles' // timeZone: specify a timezone (optional) ); console.log('Cron job scheduled and started. It will log a message every second. Press Ctrl+C to stop the process.'); // You can stop the job at any time using job.stop(). // For example, to stop after 10 seconds: // setTimeout(() => { // job.stop(); // console.log('Cron job stopped after 10 seconds.'); // }, 10000);

Debug

Known issues

breakingNode.js v16 is no longer supported by `cron` v4 and above. Projects must upgrade their Node.js environment to v18 or newer.

fix

Upgrade your Node.js installation to version 18 or higher. For example, using nvm: `nvm install 18 && nvm use 18`.

affects: >=4.0.0

breakingThe `job.running` property was renamed to `job.isActive` in v4 and became read-only. Attempts to set `job.running` will fail.

fix

Use `job.start()` to begin a job and `job.stop()` to halt it. Check `job.isActive` for the current status.

affects: >=4.0.0

breakingMonth indexing changed from `0-11` to `1-12`, and day-of-week indexing now supports `7` as Sunday (in addition to `0`).

fix

When migrating from v2 to v3, adjust all numeric month values by incrementing them by 1. Ensure day-of-week patterns account for `0` or `7` representing Sunday.

affects: >=3.0.0

breakingThe `CronJob` constructor in v3 no longer accepts a single object as its first parameter. Instead, use positional arguments or the `CronJob.from(argsObject)` static method.

fix

Rewrite `new CronJob({ ...args })` to `new CronJob(cronTime, onTick, onComplete, start, timeZone, ...)` or use `CronJob.from({ cronTime, onTick, ... })`.

affects: >=3.0.0

breakingThe ability to execute system commands via string-based inputs, relying on `child_process`, has been removed in v5 to improve browser compatibility. This functionality will no longer be available.

fix

Users who relied on string-based command execution should migrate to manually executing commands within their `onTick` function using Node.js's native `child_process` API directly.

affects: >=5.0.0-beta.1

gotchaAsynchronous `onTick` functions in older versions might not correctly catch errors, leading to silent failures or unexpected behavior.

fix

Upgrade to `cron` v4.3.4 or higher to ensure errors in async `onTick` functions are properly caught. Implement robust `try...catch` blocks within your async `onTick` handlers for older versions.

affects: <4.3.4

Errors

Common errors & fixes

Error: Your Node.js version (16.x.x) is not supported. Please upgrade to Node.js >=18.x.

Attempting to run `cron` v4 or later with an unsupported Node.js version.

fix

Upgrade your Node.js environment to version 18 or higher. Use `nvm install 18 && nvm use 18` or similar version management tools.

TypeError: Cannot set property running of #<CronJob> which has only a getter

Attempting to directly assign a value to the deprecated `job.running` property in `cron` v4 or later.

fix

Use `job.start()` to initiate the job and `job.stop()` to pause it. The job's active status can be checked via `job.isActive` (read-only).

Error: Value out of range for month (0-11)

Migrating from `cron` v2 to v3 without updating month indexes (e.g., still using '0' for January instead of '1').

fix

Adjust your cron patterns to use 1-12 for months (1=January, 12=December) and 0-7 for day-of-week (0 or 7=Sunday) as per v3 changes.

TypeError: CronJob is not a constructor

Incorrect CommonJS `require` syntax for `CronJob` or attempting to use a default import for a named export.

fix

For CommonJS, use `const { CronJob } = require('cron');`. For ESM, use `import { CronJob } from 'cron';`. Ensure it's a named import.

TypeError: Cannot read properties of undefined (reading 'from')

Attempting to use the `CronJob.from()` static method on a version of `cron` prior to v3, or if the `CronJob` object itself is undefined due to incorrect import.

fix

Ensure you are on `cron` v3 or newer to use `CronJob.from()`. Verify `CronJob` is correctly imported and available.

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

luxonoptionalProvides alternative DateTime object support for job scheduling, alongside native Date objects.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kelektiv/node-cron ↗

packagehttps://www.npmjs.com/package/cron ↗

homepagehttps://cron-job.org ↗