Add timezone option to ScheduleConfig for job scheduling

[VlatkoGoljevacki]

Problem

All cron expressions in ScheduleConfig are evaluated by croner using the server's local timezone. Most cloud environments (AWS ECS/Fargate, GCP Cloud Run, Railway, etc.) default to UTC. This
means a schedule like { cron: "0 9 * * *" } intended for "9:00 AM local time" actually fires at 9:00 UTC — which is offset by 1–2 hours depending on DST for European timezones, and up to 12+
hours for others.

This causes real bugs: in our case, daily notification jobs meant for 9:00 AM Europe/Zagreb fired at 10:00 CET (winter) and 11:00 CEST (summer). The shift on DST boundaries is especially
confusing because the behavior changes without any code change.

The underlying library (croner 9.1.0) already supports timezone-aware evaluation via { timezone: 'Europe/Zagreb' }, but Payload doesn't expose this option.

Proposed solution

Two small changes, fully backward-compatible:

1. Add timezone to ScheduleConfig

packages/payload/src/queues/config/types/index.ts:

export type ScheduleConfig = {
  cron: string
  hooks?: {
    afterSchedule?: AfterScheduleFn
    beforeSchedule?: BeforeScheduleFn
  }
  queue: string
  /**
   * IANA timezone string for cron evaluation (e.g. 'Europe/Zagreb', 'America/New_York').
   * Uses croner's built-in timezone support.
   * If omitted, the server's local timezone is used (current behavior).
   */
  timezone?: string
}

2. Pass it to croner in checkQueueableTimeConstraints

packages/payload/src/queues/operations/handleSchedules/index.ts, line 144:

  - const nextRun = new Cron(scheduleConfig.cron).nextRun(lastScheduledRun ?? undefined)
  + const cronOptions = scheduleConfig.timezone ? { timezone: scheduleConfig.timezone } : undefined
  + const nextRun = new Cron(scheduleConfig.cron, cronOptions).nextRun(lastScheduledRun ?? undefined)

  Usage

  export const myTaskConfig = {
    slug: 'daily-report',
    schedule: [{
      cron: '0 9 * * *',
      queue: 'default',
      timezone: 'Europe/Zagreb', // 9:00 AM Croatian time, DST-aware
    }],
    handler: myHandler,
  } satisfies TaskConfig

Why this matters

• No new dependencies — croner 9.1.0 (already bundled) has full IANA timezone support
• Fully backward-compatible — optional field, omitting it preserves current behavior
• DST-safe — croner handles DST transitions automatically via the OS timezone database
• Affects everyone on UTC servers — which is the default for Docker (node:*-slim), most cloud providers, and CI environments

Current workaround

We use the beforeSchedule hook to recompute waitUntil with a timezone-aware croner instance, calling defaultBeforeSchedule first to preserve the duplicate-job prevention logic:

  import { Cron } from 'croner'
  import type { BeforeScheduleFn, ScheduleConfig } from 'payload'

  export const createTzSchedule = (
    cron: string,
    queue: string,
    timezone: string,
  ): ScheduleConfig => ({
    cron,
    queue,
    hooks: {
      beforeSchedule: async ({ defaultBeforeSchedule, jobStats, queueable, req }) => {
        const result = await defaultBeforeSchedule({ defaultBeforeSchedule, jobStats, queueable, req })
        if (!result.shouldSchedule) return result

        const taskSlug = queueable.taskConfig?.slug
        const workflowSlug = queueable.workflowConfig?.slug
        const queueStats = jobStats?.stats?.scheduledRuns?.queues?.[queue]
        const lastRun = taskSlug
          ? queueStats?.tasks?.[taskSlug]?.lastScheduledRun
          : queueStats?.workflows?.[workflowSlug ?? '']?.lastScheduledRun

        const nextRun = new Cron(cron, { timezone }).nextRun(lastRun ?? undefined)

        return { ...result, waitUntil: nextRun ?? result.waitUntil }
      },
    },
  })

This works but requires every scheduled task to use the wrapper, and the lastScheduledRun lookup duplicates internal logic from checkQueueableTimeConstraints. The native two-line fix would
eliminate this entirely.

[andershermansen]

This is a very good suggestion! I also had this issue and sometimes wanted cron to be in a local timezone.