Recurring Jobs
Run an outbox job on a cron: one Void cron file per schedule with defineOutboxSchedule, enqueued once per tick.
A recurring job is a Void cron file. Its export const cron is the schedule, written once:
// apps/web/crons/weekly-digest.tsimport { weeklyDigest } from '#/jobs/weekly-digest.job.ts';import { defineOutboxSchedule } from '#/lib/outbox.server.ts';export const cron = '0 9 * * MON';export default defineOutboxSchedule({ job: weeklyDigest, payload: ({ scheduledAt }) => ({ week: scheduledAt.toISOString().slice(0, 10) }),});On each tick the occurrence's job is enqueued (and nudged), then it runs like any other job, with retries, timeouts and replay. The job must be in outboxJobs (Jobs); the payload is type-checked against it.
- Once per tick. The job's dedupe key is
schedule:<name>:<tick time>, so a tick Cloudflare delivers twice enqueues nothing new. PassdedupeKey: ({ scheduledAt }) => …to choose your own; two schedules of the same job need differentnames (the key usesname, which defaults to the kind), or when both fire in the same minute the second one's occurrence is dropped asexists. - Cron runs in UTC, to the minute. A trigger can fire a little late. Not for work that must happen at an exact second.
- A missed tick is skipped, not caught up. If Cloudflare doesn't fire it, that occurrence never runs. Watch the logs for
outbox schedule_failedand enqueue by hand when it matters. - Checked when the file loads. A job missing from
outboxJobs, or a schedule the package rejects, fails loudly instead of silently never running.
Several Jobs Per Tick
run gets the tick's transaction (tx) and an enqueue; everything it enqueues commits together. tx is the outbox's own connection, without the app's schema or relations: read with void/db as below, and use tx only for raw SQL that must be in the same transaction. Derive every dedupe key from scheduledAt, so a repeated tick finds the jobs it already made:
// apps/web/crons/nightly-sync.tsimport { db } from 'void/db';import { syncOrganization } from '#/jobs/sync-organization.job.ts';import { defineOutboxSchedule } from '#/lib/outbox.server.ts';export const cron = '0 2 * * *';export default defineOutboxSchedule({ name: 'nightly-sync', jobs: [syncOrganization], // required: each must be in outboxJobs, checked when the file loads async run({ scheduledAt, enqueue }) { const day = scheduledAt.toISOString().slice(0, 10); const organizations = await db.query.organization.findMany({ columns: { id: true } }); for (const { id } of organizations) { await enqueue(syncOrganization, { payload: { organizationId: id, day }, dedupeKey: `sync:${id}:${day}`, tenantKey: id, }); } },});A refused enqueue throws, which rolls the whole occurrence back and logs outbox schedule_failed: nothing is enqueued for that tick. Keep run to reads and enqueues; the work belongs in the jobs.
Cost
Each schedule tick also runs the outbox sweep (the package has no schedule-only handler yet), next to the kit's */5 sweep. Two crons firing in the same minute run two short, lease-safe sweeps, each holding a database connection briefly. Prefer a handful of schedules with run fan-out over one cron file per tenant.
Locally
Crons don't fire in vp dev. Trigger one with the POST /__void/scheduled command Void prints when the dev server starts (it carries a dev token), with your file's cron:
curl -X POST http://localhost:5173/__void/scheduled \ -H "Content-Type: application/json" \ -H "x-void-dev-trigger: <printed-token>" \ -d '{"cron":"0 9 * * MON","scheduledTime":'"$(date +%s000)"'}'Each request carries a new scheduledTime, so each one enqueues a new occurrence; send the same value twice to see the second one enqueue nothing. The same request with "cron":"*/5 * * * *" runs the sweep. Without the token it answers 401: the endpoint isn't open, and CRON_SECRET doesn't apply to this app.