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.ts
import { 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. Pass dedupeKey: ({ scheduledAt }) => … to choose your own; two schedules of the same job need different names (the key uses name, which defaults to the kind), or when both fire in the same minute the second one's occurrence is dropped as exists.
  • 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_failed and 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.ts
import { 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.