feat: crons for all bin scripts, new jobs:handle-schedules script, more reliable job system crons #13564

AlessioGr · 2025-08-23T00:07:47Z

New jobs:handle-schedules bin script

Similarly to payload jobs:run, this PR adds a new jobs:handle-schedules bin script which only handles scheduling.

Allows jobs:run bin script to handle scheduling

Similarly to how payload autoRun handles both running and scheduling jobs by default, you can now set the payload jobs:run bin script to also handle scheduling. This is opt-in:

pnpm payload jobs:run --cron "*/5 * * * *" --queue myQueue --handle-schedules # This will both schedule jobs according to the configuration and run them

Cron schedules for all bin scripts

Previously, only the payload jobs:run bin script accepted a cron flag. The payload jobs:handle-schedules would have required the same logic to also handle a cron flag.

Instead of opting for this duplicative logic, I'm now handling cron logic before we determine which script to run. This means: it's simpler and requires less duplicative code.

This allows all other bin scripts (including custom ones) to use the --cron flag, enabling cool use-cases like scheduling your own custom scripts - no additional config required!

Example:

pnpm payload run ./myScript.ts --cron "0 * * * *"

Video Example:

Screenshot.2025-08-22.at.17.28.07.mp4

More reliable job system crons

When using autorun or --cron, if one cron run takes longer than the cron interval, the second cron would run before the first one finishes.

This can be especially dangerous when running jobs using a bin script, potentially causing race conditions, as the first cron run will take longer due to payload initialization overhead (only for first cron run, consecutive ones use cached payload). Now, consecutive cron runs will wait for the first one to finish by using the { protect: true } property of Croner.

This change will affect both autorun and bin scripts.

Cleanup

Centralized payload instance cleanup (payload.destroy()) for all bin scripts
The getPayload function arguments were not properly typed. Arguments like disableOnInit: true are already supported, but the type did not reflect that. This simplifies the type and makes it more accurate.

Fixes

allQueues argument for payload jobs:run was not respected

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1210982048221258
- https://app.asana.com/0/0/1211124797199077

github-actions · 2025-08-23T00:13:07Z

📦 esbuild Bundle Analysis for payload

This analysis was generated by esbuild-bundle-analyzer. 🤖

Meta File	Out File	Size (raw)	Note
packages/next/meta_index.json	esbuild/index.js	753.94 KB	🆕 Added
packages/payload/meta_index.json	esbuild/index.js	1.21 MB	🆕 Added
packages/payload/meta_shared.json	esbuild/exports/shared.js	161.98 KB	🆕 Added
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	259.50 KB	🆕 Added
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.15 MB	🆕 Added
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	14.20 KB	🆕 Added

Largest paths

These visualization shows top 20 largest paths in the bundle.

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████████ }}}$ 80.3%, 601.88 KB
dist/views/Version	${{\color{Goldenrod}{ █▋ }}}$ 6.7%, 50.09 KB
dist/views/Document	${{\color{Goldenrod}{ ▌ }}}$ 2.0%, 14.91 KB
dist/views/List	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 9.16 KB
dist/views/Root	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 7.08 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 6.30 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 5.98 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 5.32 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 4.84 KB
dist/elements/DocumentHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 4.81 KB
dist/views/Login	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 4.39 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 3.68 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.4%, 3.09 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.4%, 3.09 KB
dist/utilities/initPage	${{\color{Goldenrod}{ }}}$ 0.4%, 3.06 KB
dist/templates/Default	${{\color{Goldenrod}{ }}}$ 0.4%, 2.83 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.3%, 2.61 KB
dist/views/BrowseByFolder	${{\color{Goldenrod}{ }}}$ 0.3%, 2.60 KB
dist/views/CollectionFolders	${{\color{Goldenrod}{ }}}$ 0.3%, 2.46 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 2.41 KB
(other)	${{\color{Goldenrod}{ ████▉ }}}$ 19.7%, 147.38 KB

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████▍ }}}$ 69.8%, 841.07 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.3%, 40.21 KB
dist/collections/operations	${{\color{Goldenrod}{ ▊ }}}$ 3.0%, 36.01 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.22 KB
dist/queues/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.00 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 11.54 KB
dist/globals/operations	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 11.12 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 10.82 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 9.38 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.27 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.79 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.79 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.74 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.42 KB
dist/collections/endpoints	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.20 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.25 KB
dist/auth/strategies	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 5.50 KB
dist/config/sanitize.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 5.44 KB
dist/auth/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 5.41 KB
dist/utilities/telemetry	${{\color{Goldenrod}{ }}}$ 0.4%, 5.31 KB
(other)	${{\color{Goldenrod}{ ███████▌ }}}$ 30.2%, 364.07 KB

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████████ }}}$ 80.0%, 126.93 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▍ }}}$ 5.9%, 9.38 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 2.48 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 1.41 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.28 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 943 B
dist/utilities/fieldSchemaToJSON.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 917 B
dist/folders/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 916 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.4%, 713 B
dist/collections/config	${{\color{Goldenrod}{ }}}$ 0.4%, 570 B
dist/bin/generateImportMap	${{\color{Goldenrod}{ }}}$ 0.4%, 559 B
dist/auth/sessions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 545 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.3%, 423 B
dist/utilities/deepMerge.js	${{\color{Goldenrod}{ }}}$ 0.3%, 413 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.2%, 391 B
dist/utilities/formatLabels.js	${{\color{Goldenrod}{ }}}$ 0.2%, 380 B
dist/utilities/transformColumnPreferences.js	${{\color{Goldenrod}{ }}}$ 0.2%, 348 B
(other)	${{\color{Goldenrod}{ █████ }}}$ 20.0%, 31.82 KB

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
dist/lexical/plugins	${{\color{Goldenrod}{ ███ }}}$ 12.1%, 30.91 KB
dist/features/experimental_table	${{\color{Goldenrod}{ ██▍ }}}$ 9.6%, 24.60 KB
dist/lexical/ui	${{\color{Goldenrod}{ ██▎ }}}$ 9.2%, 23.47 KB
dist/features/blocks	${{\color{Goldenrod}{ ██▏ }}}$ 8.7%, 22.43 KB
dist/packages/@lexical	${{\color{Goldenrod}{ █▊ }}}$ 7.4%, 18.99 KB
dist/features/link	${{\color{Goldenrod}{ █▊ }}}$ 7.0%, 17.96 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▋ }}}$ 6.9%, 17.68 KB
dist/features/textState	${{\color{Goldenrod}{ █ }}}$ 4.3%, 10.98 KB
dist/features/upload	${{\color{Goldenrod}{ ▉ }}}$ 3.7%, 9.60 KB
dist/features/relationship	${{\color{Goldenrod}{ ▉ }}}$ 3.7%, 9.41 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▊ }}}$ 3.1%, 8.08 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 7.39 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.7%, 7.04 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▋ }}}$ 2.7%, 7.01 KB
dist/lexical/config	${{\color{Goldenrod}{ ▌ }}}$ 2.0%, 5.10 KB
dist/features/lists	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 4.95 KB
dist/lexical/theme	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 4.01 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 3.46 KB
dist/lexical/LexicalEditor.js	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 3.23 KB
dist/features/indent	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 2.50 KB
(other)	${{\color{Goldenrod}{ █████████████████████▉ }}}$ 87.9%, 225.57 KB

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████▌ }}}$ 50.3%, 572.93 KB
dist/elements/FolderView	${{\color{Goldenrod}{ ▋ }}}$ 2.7%, 30.37 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 24.57 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 16.26 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 16.11 KB
dist/views/Edit	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.43 KB
dist/elements/Table	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.26 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 14.82 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 12.43 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 11.94 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 9.30 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 9.08 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 8.57 KB
dist/providers/Folders	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.20 KB
dist/elements/ListHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.98 KB
dist/views/CollectionFolder	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.89 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.81 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.18 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.91 KB
(other)	${{\color{Goldenrod}{ ████████████▍ }}}$ 49.7%, 566.12 KB

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ █████▋ }}}$ 22.9%, 3.12 KB
../../node_modules	${{\color{Goldenrod}{ ████▉ }}}$ 19.5%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▊ }}}$ 11.2%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ ██▍ }}}$ 9.7%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▌ }}}$ 6.3%, 862 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █▌ }}}$ 6.0%, 814 B
dist/utilities/api.js	${{\color{Goldenrod}{ █▍ }}}$ 5.6%, 756 B
dist/elements/Translation	${{\color{Goldenrod}{ ▉ }}}$ 3.6%, 493 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 339 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 251 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 168 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 159 B
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 147 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 146 B
dist/utilities/hasSavePermission.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 136 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 129 B
dist/utilities/findLocaleFromCode.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 84 B
dist/utilities/sanitizeID.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 77 B
dist/utilities/isEditing.js	${{\color{Goldenrod}{ }}}$ 0.4%, 59 B
(other)	${{\color{Goldenrod}{ ███████████████████▎ }}}$ 77.1%, 10.49 KB

Details

Next to the size is how much the size has increased or decreased compared with the base branch of this PR.

‼️: Size increased by 20% or more. Special attention should be given to this.
⚠️: Size increased in acceptable range (lower than 20%).
✅: No change or even downsized.
🗑️: The out file is deleted: not found in base branch.
🆕: The out file is newly found: will be added to base branch.

DanRibbens

I should have brought this up on the earlier PR that added payload.jobs.handleSchedules() but then it was seemingly used only internally. Now you're exposing it so we should make sure we want to stick with it or not.

docs/jobs-queue/queues.mdx

DanRibbens · 2025-08-25T14:00:51Z

docs/jobs-queue/schedules.mdx

+pnpm payload jobs:run --cron "*/5 * * * *" --queue myQueue --handle-schedules # This will both schedule jobs according to the configuration and run them
+```
+
+If you only want to handle schedules, you can use the dedicated `jobs:handle-schedules` bin script:


I would prefer to call it just jobs:schedule.
payload.jobs.handleSchedules() is also verbose, payload.jobs.schedule() would have been fine.

What do you think?

…-handle-schedules

github-actions · 2025-09-17T13:36:20Z

🚀 This is included in version v3.56.0

AlessioGr added 3 commits August 22, 2025 16:56

feat: crons for all bin scripts, new jobs:handle-schedules script

7006673

improve docs

eabd489

support disableDBConnect in hmr

84621da

github-actions bot added the created-by: Payload team label Aug 23, 2025

AlessioGr enabled auto-merge (squash) August 23, 2025 06:47

AlessioGr added 3 commits August 22, 2025 23:59

fix allQueues and handleSchedules args

07ae258

do not run next cron if previous cron is still running

88b52d6

Do not run consecutive crons if previous crons still ongoing

bdc84f3

AlessioGr changed the title ~~feat: crons for all bin scripts, new jobs:handle-schedules script~~ feat: crons for all bin scripts, new jobs:handle-schedules script, more reliable job system crons Aug 23, 2025

AlessioGr disabled auto-merge August 23, 2025 07:26

AlessioGr enabled auto-merge (squash) August 23, 2025 07:26

DanRibbens requested changes Aug 25, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into feat/bin-scripts-cron…

f73b7ca

…-handle-schedules

AlessioGr requested a review from DanRibbens August 27, 2025 20:27

DanRibbens approved these changes Sep 15, 2025

View reviewed changes

AlessioGr merged commit cdeb828 into main Sep 15, 2025
83 checks passed

AlessioGr deleted the feat/bin-scripts-cron-handle-schedules branch September 15, 2025 17:15

This was referenced Sep 15, 2025

fix: exit payload generate:importmap and generate:types after completion #13802

Closed

generate:importmap and generate:types don't have process.exit #13744

Closed

r1tsuu mentioned this pull request Sep 30, 2025

[Regression] [2.56] payload run command does not work #13969

Closed

jefferyto mentioned this pull request Nov 11, 2025

feat: allow custom bin scripts to return payload instance and exit code #14254

Open

bobbyo mentioned this pull request Feb 8, 2026

generate:types hangs after completing (regression in 3.73.0, was fixed in 3.56.0) #15553

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: crons for all bin scripts, new jobs:handle-schedules script, more reliable job system crons #13564

feat: crons for all bin scripts, new jobs:handle-schedules script, more reliable job system crons #13564

Uh oh!

AlessioGr commented Aug 23, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Aug 23, 2025 •

edited

Loading

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Uh oh!

DanRibbens left a comment

Uh oh!

Uh oh!

DanRibbens Aug 25, 2025

Uh oh!

Uh oh!

github-actions bot commented Sep 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: crons for all bin scripts, new jobs:handle-schedules script, more reliable job system crons #13564

feat: crons for all bin scripts, new jobs:handle-schedules script, more reliable job system crons #13564

Uh oh!

Conversation

AlessioGr commented Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New jobs:handle-schedules bin script

Allows jobs:run bin script to handle scheduling

Cron schedules for all bin scripts

More reliable job system crons

Cleanup

Fixes

Uh oh!

github-actions bot commented Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 esbuild Bundle Analysis for payload

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Uh oh!

DanRibbens left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DanRibbens Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Sep 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AlessioGr commented Aug 23, 2025 •

edited

Loading

github-actions bot commented Aug 23, 2025 •

edited

Loading