# Recurring Jobs

> Run an outbox job on a cron: one Void cron file per schedule with defineOutboxSchedule, enqueued once per tick.

*Canonical: https://makerkit.dev/docs/void-cloudflare/outbox/schedules*

---

A recurring job is a Void cron file. Its `export const cron` is the schedule, written once:

```ts
// 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](./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 `name`s (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:

```ts
// 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`:

```bash
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.
