Registry / workflow / cron-schedule

cron-schedule

JSON →
library1.1jsnpmunverified

cron-schedule is a robust, zero-dependency library designed for parsing cron expressions and scheduling tasks across Node.js, Deno, and browser environments. The current stable version is 6.0.0. The project maintains an active release cadence, frequently publishing patch and minor versions to address bugs and introduce features, with major versions typically aligning with Node.js End-of-Life cycles to ensure compatibility with modern runtime environments. Key differentiators include its complete lack of external dependencies, support for a wide range of JavaScript runtimes, a lightweight footprint, and full tree-shakeability. It provides comprehensive functionalities for parsing cron strings, calculating next or previous scheduled dates, generating date iterators, and directly scheduling function calls based on cron patterns. The library also offers full TypeScript support and is published on JSR, making it a versatile choice for various JavaScript/TypeScript projects.

npm install cron-schedule
INSTALL
IMPORT
SIG · CRON-SCHEDULE
C
cron-schedule
workflowjavascriptv1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

parseCronExpression
import { parseCronExpression } from 'cron-schedule';
const { parseCronExpression } = require('cron-schedule');
ESM-only since v4.0.0. This is the primary function for parsing cron strings.
createCronScheduler
import { createCronScheduler } from 'cron-schedule/schedulers';
import { createCronScheduler } from 'cron-schedule';
Used for scheduling functions. Note the specific subpath 'cron-schedule/schedulers'. For environments without conditional exports, use 'cron-schedule/dist/schedulers' for v4.0.0+.
CronExpression
import type { CronExpression } from 'cron-schedule';
TypeScript type for the object returned by parseCronExpression. Essential for type-safe usage.

Demonstrates parsing a cron expression to calculate next occurrences and how to set up a basic, albeit short-lived, cron job scheduler.

import { parseCronExpression, createCronScheduler } from 'cron-schedule'; // 1. Parsing a cron expression and calculating future dates const cronExpressionString = '0 0 * * MON-FRI'; // At 00:00 on every weekday (Monday through Friday) const cron = parseCronExpression(cronExpressionString); const startDate = new Date('2026-04-21T00:00:00.000Z'); // A Monday for demonstration console.log(`Starting date: ${startDate.toISOString()}`); const nextDate = cron.getNextDate(startDate); console.log(`Next scheduled date: ${nextDate.toISOString()}`); const nextFiveDates = cron.getNextDates(5, startDate); console.log('Next five scheduled dates:'); nextFiveDates.forEach((date, index) => { console.log(` ${index + 1}: ${date.toISOString()}`); }); // 2. Setting up a basic scheduler (note: this only sets it up, it won't run in a short-lived script) // In a real application, this would run indefinitely in a Node.js process. const dailyJob = createCronScheduler('0 0 * * *', () => { console.log(`Daily job executed at ${new Date().toISOString()}`); }); console.log('\nScheduler for "0 0 * * *" created (runs daily at midnight). It will execute in a long-running process.'); // To prevent the quickstart from hanging, we'll stop it immediately for demo purposes. dailyJob.stop(); console.log('Scheduler stopped immediately for quickstart demonstration.');
Debug
Known issues
breakingSupport for Node.js 18 (which reached End of Life) has been dropped.
fix
Upgrade your Node.js environment to version 20, 22, or 24.
affects: >=6.0.0
breakingSupport for Node.js 14 was dropped due to its End of Life and missing ESM module support.
fix
Upgrade your Node.js environment to version 16 or higher (20+ for v6).
affects: >=4.0.0
breakingFor environments that do not support conditional exports, the import path for schedulers was changed.
fix
If experiencing import issues with schedulers, change your import statement from `import { createCronScheduler } from 'cron-schedule/schedulers'` to `import { createCronScheduler } from 'cron-schedule/dist/schedulers'`.
affects: >=4.0.0-next.2
gotchaVersion 5.0.0 was not published to npm due to a build error.
fix
Do not install or use `cron-schedule@5.0.0`. Instead, use `cron-schedule@5.0.1` or any subsequent version.
affects: =5.0.0
gotchaThe library transitioned to an ESM-only build in version 4.0.0.
fix
Ensure you are using ECMAScript module imports (`import ... from 'package'`) rather than CommonJS `require()` syntax.
affects: >=4.0.0
Errors
Common errors & fixes
Incorrect date returned when using the @monthly cron macro.
A bug in the cron parser for the `@monthly` macro.
fix
Update to `cron-schedule@5.0.4` or a newer version.
Weekday ranges including Sunday (e.g., '0-7' or 'SUN-SAT') are parsed incorrectly.
Bugs in handling Sunday in weekday ranges, particularly when Sunday starts a range.
fix
Update to `cron-schedule@5.0.3` or a newer version for correct Sunday range starting, and `cron-schedule@4.0.0` or newer for general Sunday range parsing fixes.
cron.getPrevDate() returns a wrong result for months with fewer than 31 days.
An edge case bug in the `getPrevDate` calculation logic.
fix
Update to `cron-schedule@5.0.1` or a newer version.
Cron expression parsing fails or produces incorrect results with extra whitespace characters.
The parser was not sufficiently resilient to handle arbitrary extra whitespaces within cron expressions.
fix
Update to `cron-schedule@5.0.2` or a newer version which includes improved whitespace handling.
Upgrade
Version history
1.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources
cron-schedule — npm install cron-schedule · libregistry