{"id":10687,"library":"cron","title":"Node.js Cron Job Scheduler","description":"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.","status":"active","version":"4.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/kelektiv/node-cron","tags":["javascript","cron","node cron","node-cron","schedule","scheduler","cronjob","cron job","typescript"],"install":[{"cmd":"npm install cron","lang":"bash","label":"npm"},{"cmd":"yarn add cron","lang":"bash","label":"yarn"},{"cmd":"pnpm add cron","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides alternative DateTime object support for job scheduling, alongside native Date objects.","package":"luxon","optional":true}],"imports":[{"note":"The primary class for creating and managing scheduled tasks. ESM is the recommended import style; CommonJS can use `const { CronJob } = require('cron');`.","wrong":"const CronJob = require('cron').CronJob;","symbol":"CronJob","correct":"import { CronJob } from 'cron';"},{"note":"Used for advanced manipulation and parsing of cron time patterns. Typically used internally or for validation.","wrong":"const CronTime = require('cron').CronTime;","symbol":"CronTime","correct":"import { CronTime } from 'cron';"},{"note":"TypeScript type definition for the parameters accepted by the CronJob constructor or `CronJob.from` static method.","symbol":"CronJobParameters","correct":"import type { CronJobParameters } from 'cron';"}],"quickstart":{"code":"import { CronJob } from 'cron';\n\n// This job runs every second, logging a message to the console.\n// The cronTime pattern '* * * * * *' specifies: second, minute, hour, day of month, month, day of week.\nconst job = new CronJob(\n\t'* * * * * *', // cronTime: run every second\n\tfunction () {\n\t\tconst now = new Date();\n\t\tconsole.log('You will see this message every second:', now.toLocaleTimeString());\n\t}, // onTick: function to execute when the job runs\n\tnull, // onComplete: function to execute when the job stops (optional)\n\ttrue, // start: boolean to start the job immediately\n\t'America/Los_Angeles' // timeZone: specify a timezone (optional)\n);\n\nconsole.log('Cron job scheduled and started. It will log a message every second. Press Ctrl+C to stop the process.');\n\n// You can stop the job at any time using job.stop().\n// For example, to stop after 10 seconds:\n// setTimeout(() => {\n//   job.stop();\n//   console.log('Cron job stopped after 10 seconds.');\n// }, 10000);","lang":"typescript","description":"Schedules a function to run every second using a cron string and demonstrates basic job creation and immediate start."},"warnings":[{"fix":"Upgrade your Node.js installation to version 18 or higher. For example, using nvm: `nvm install 18 && nvm use 18`.","message":"Node.js v16 is no longer supported by `cron` v4 and above. Projects must upgrade their Node.js environment to v18 or newer.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use `job.start()` to begin a job and `job.stop()` to halt it. Check `job.isActive` for the current status.","message":"The `job.running` property was renamed to `job.isActive` in v4 and became read-only. Attempts to set `job.running` will fail.","severity":"breaking","affected_versions":">=4.0.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.","message":"Month indexing changed from `0-11` to `1-12`, and day-of-week indexing now supports `7` as Sunday (in addition to `0`).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Rewrite `new CronJob({ ...args })` to `new CronJob(cronTime, onTick, onComplete, start, timeZone, ...)` or use `CronJob.from({ cronTime, onTick, ... })`.","message":"The `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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=5.0.0-beta.1"},{"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.","message":"Asynchronous `onTick` functions in older versions might not correctly catch errors, leading to silent failures or unexpected behavior.","severity":"gotcha","affected_versions":"<4.3.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 18 or higher. Use `nvm install 18 && nvm use 18` or similar version management tools.","cause":"Attempting to run `cron` v4 or later with an unsupported Node.js version.","error":"Error: Your Node.js version (16.x.x) is not supported. Please upgrade to Node.js >=18.x."},{"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).","cause":"Attempting to directly assign a value to the deprecated `job.running` property in `cron` v4 or later.","error":"TypeError: Cannot set property running of #<CronJob> which has only a getter"},{"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.","cause":"Migrating from `cron` v2 to v3 without updating month indexes (e.g., still using '0' for January instead of '1').","error":"Error: Value out of range for month (0-11)"},{"fix":"For CommonJS, use `const { CronJob } = require('cron');`. For ESM, use `import { CronJob } from 'cron';`. Ensure it's a named import.","cause":"Incorrect CommonJS `require` syntax for `CronJob` or attempting to use a default import for a named export.","error":"TypeError: CronJob is not a constructor"},{"fix":"Ensure you are on `cron` v3 or newer to use `CronJob.from()`. Verify `CronJob` is correctly imported and available.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'from')"}],"ecosystem":"npm"}