cron

Schedule an in-process cron job that calls a function on a schedule.

Unlike the module-path overload, this runs the callback on the current event loop — the job dies with the process and does not survive reboots. State is shared between invocations (closures, module-level variables, database connections all persist).

No-overlap guarantee#

The next fire time is computed only after the callback settles (including any returned Promise). If your callback takes 3 minutes and runs every minute, it fires at T+0 → runs until T+3 → next fire is the first minute boundary after T+3. Invocations never stack.

Error semantics#

Matches setTimeout: a synchronous throw emits uncaughtException, a rejected Promise emits unhandledRejection. Without a listener, the process exits with code 1. The job reschedules itself after an error — it does not stop on first failure.

process.on("unhandledRejection", (err) => log.error(err)); // keep going
Bun.cron("* * * * *", async () => { await mightThrow(); });

Cron expression syntax#

Five fields: minute hour day-of-month month day-of-week.

• 0 and 7 both mean Sunday.
• Month and weekday names are case-insensitive (MON, Monday, jan, January all work).
• Nicknames: @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly.
• When both day-of-month and day-of-week are restricted (neither is *), the job fires when either matches — POSIX cron OR semantics.
• All expressions work on all platforms — there is no Windows trigger limit here.

Lifecycle & --hot#

Under bun --hot, all in-process cron jobs are stopped immediately before the module graph is re-evaluated. Each Bun.cron() call still in your source then re-registers, so editing the schedule, editing the callback, or deleting the line entirely all take effect on save without leaking timers.

By default the job keeps the process alive (like setInterval); call .unref() to let the process exit naturally when nothing else is pending.

Register an OS-level cron job that runs a JavaScript/TypeScript module on a schedule.

Unlike the callback overload, this registers the job with the operating system's scheduler — the job survives process exit and persists across reboots. Bun spawns a fresh process for each invocation, so there is no shared state between runs.

Module shape#

The target module must have a default export with a scheduled(controller) method, matching the Cloudflare Workers Cron Triggers API. The controller exposes cron (the expression) and scheduledTime (ms since epoch).

// worker.ts
export default {
  async scheduled(controller: Bun.CronController) {
    console.log(`Fired: ${controller.cron} at ${new Date(controller.scheduledTime)}`);
    await doWork();
  },
};

Cron expression syntax#

Five fields: minute hour day-of-month month day-of-week.

• 0 and 7 both mean Sunday.
• Month and weekday names are case-insensitive (MON, Monday, jan, January all work).
• Nicknames: @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly.
• When both day-of-month and day-of-week are restricted (neither is *), the job fires when either matches — POSIX cron OR semantics.

Platform caveats#

• Windows: minute steps that don't evenly divide 60 (e.g. */7, */11) with all hours active exceed Task Scheduler's 48-trigger limit and throw. Divisors of 60 (*/5, */10, */15, */20, */30) and all common patterns work.
• Windows headless/CI: registration fails if the current user's SID can't be resolved (typical under service accounts). Run as a regular user or create the task manually with schtasks /create /ru SYSTEM.
• macOS: stdout/stderr are written to /tmp/bun.cron.<title>.{stdout,stderr}.log.

Idempotency & removal#

Registering with a title that already exists replaces the previous entry. Use Bun.cron.remove to unregister. The title is namespaced per user, so different users can register jobs with the same title independently.