{"id":11453,"library":"node-schedule","title":"Node Schedule","description":"Node Schedule is a robust and flexible job scheduler for Node.js, designed for time-based scheduling rather than simple intervals. It enables developers to execute arbitrary functions at specific dates and times, supporting intricate recurrence rules similar to cron, as well as one-off scheduled events. The current stable version is 2.1.1. The library differentiates itself by using only a single timer for all scheduled jobs, optimizing resource usage. Unlike traditional `cron`, it offers cross-platform support, including Windows, due to its JavaScript implementation. It's crucial to understand that `node-schedule` is an in-process scheduler, meaning jobs only run as long as the Node.js process is active and are not persisted across application restarts. For persistent or distributed job scheduling, alternatives like Agenda or Bree should be considered.","status":"active","version":"2.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/node-schedule/node-schedule","tags":["javascript","schedule","task","job","cron","recurrent","in-memory"],"install":[{"cmd":"npm install node-schedule","lang":"bash","label":"npm"},{"cmd":"yarn add node-schedule","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-schedule","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `scheduleJob` function is a named export, not the default export.","wrong":"import scheduleJob from 'node-schedule';","symbol":"scheduleJob","correct":"import { scheduleJob } from 'node-schedule';"},{"note":"The `Job` class allows for manual job creation and direct manipulation.","symbol":"Job","correct":"import { Job } from 'node-schedule';"},{"note":"While destructuring `require` might work, the common pattern is to import the entire module and access properties like `schedule.scheduleJob`.","wrong":"const { scheduleJob } = require('node-schedule');","symbol":"All exports (CommonJS)","correct":"const schedule = require('node-schedule');"}],"quickstart":{"code":"import { scheduleJob } from 'node-schedule';\n\n// Schedule a job using cron syntax\nconst cronJob = scheduleJob('*/5 * * * * *', function(){\n  console.log('Cron job ran: The answer to life, the universe, and everything!');\n});\n\ncronJob.on('success', (result) => {\n  console.log(`Cron job successful with result: ${result}`);\n});\ncronJob.on('error', (err) => {\n  console.error(`Cron job failed: ${err.message}`);\n});\n\n// Schedule a job for a specific date/time\nconst now = new Date();\nconst futureDate = new Date(now.getTime() + 10 * 1000); // 10 seconds from now\n\nconst dateJob = scheduleJob(futureDate, function(){\n  console.log('Date job ran: This job fired exactly at the scheduled time!');\n});\n\ndateJob.on('success', (result) => {\n  console.log(`Date job successful with result: ${result}`);\n});\ndateJob.on('canceled', (scheduledTime) => {\n  console.log(`Date job canceled before execution, scheduled for ${scheduledTime}`);\n});\n\nconsole.log(`Scheduled cron job to run every 5 seconds. Current time: ${now.toLocaleTimeString()}`);\nconsole.log(`Scheduled date job to run at: ${futureDate.toLocaleTimeString()}`);\n\n// Example of canceling a job (uncomment to test)\n// setTimeout(() => {\n//   dateJob.cancel();\n//   console.log('Date job explicitly canceled.');\n// }, 5000);\n\n// Graceful shutdown (requires '2.1.0' or newer)\n// process.on('SIGTERM', async () => {\n//   console.log('SIGTERM received, initiating graceful shutdown...');\n//   await scheduleJob.gracefulShutdown();\n//   console.log('All scheduled jobs stopped. Exiting.');\n//   process.exit(0);\n// });","lang":"javascript","description":"Schedules a recurring job using cron syntax and a one-time job for a future date, demonstrating job creation, event handling, and basic usage."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 6 or newer to ensure compatibility and stability.","message":"Version 2.0.0 dropped official support for Node.js versions older than 6. Running on older versions may lead to unexpected behavior or failures.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Refactor job definitions to pass a function directly or instantiate a `Job` object explicitly, then schedule it. For example, `scheduleJob(rule, () => {})` instead of `scheduleJob({ rule: rule, job: () => {} })`.","message":"In version 2.0.0, direct support for 'job objects' as arguments to `scheduleJob` was removed. The API now primarily expects functions or a `Job` instance. Refer to `UPGRADING.md` for detailed migration steps.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"For durable or persistent jobs that need to survive application restarts or run in multi-node environments, consider using external solutions like actual `cron`, `Agenda`, or `Bree`.","message":"`node-schedule` is an in-process scheduler; jobs are transient and only persist as long as your Node.js application is running. Scheduled jobs will be lost upon application restart.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Evaluate if your scheduling needs are truly time-based. For simple recurring intervals, consider `toad-scheduler` or native Node.js timers (`setInterval`) for better fit and potentially simpler implementation.","message":"This library is optimized for time-based, complex scheduling (e.g., 'every third Tuesday') rather than simple interval-based tasks (e.g., 'every 5 minutes'). While possible, simpler interval scheduling might be better handled by `toad-scheduler` or `setInterval`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your event listeners correctly subscribe to `job.on('canceled', ...)`.","message":"The `canceled` event, emitted when an invocation is canceled before execution, uses the American spelling 'canceled' (single 'L').","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { scheduleJob } from 'node-schedule';` for ESM or `const schedule = require('node-schedule'); schedule.scheduleJob(...)` for CommonJS.","cause":"Attempting to use `scheduleJob` from an incorrect import or `require` pattern, often due to CommonJS vs. ESM module differences or improper destructuring.","error":"TypeError: scheduleJob is not a function"},{"fix":"For jobs that must persist across application restarts, use a durable job scheduler like `Agenda` or `Bree`, or consider system-level `cron`.","cause":"`node-schedule` is an in-process scheduler, meaning all scheduled jobs are stored in memory and are lost when the Node.js process exits.","error":"My scheduled jobs are not running after I restart my application."},{"fix":"Double-check your cron pattern against standard cron format. Ensure that your job callbacks are asynchronous or quickly executed to avoid blocking the event loop. For complex or long-running tasks, consider offloading them to worker threads or separate processes.","cause":"This can occur if the cron pattern is misunderstood, the system clock changes, or the Node.js event loop is blocked for extended periods by synchronous, CPU-intensive tasks.","error":"Jobs are running at unexpected times or missing executions."},{"fix":"Upgrade to `node-schedule` version 2.0.0 or later, as these issues were addressed in that release.","cause":"Versions of `node-schedule` prior to 2.0.0 had known memory leak issues, especially with one-off jobs that were not properly de-referenced.","error":"My application is consuming increasing amounts of memory over time, particularly with many one-off jobs."}],"ecosystem":"npm"}