Defining and Enqueuing Jobs
Define an outbox job with defineOutboxJob, list it, enqueue it inside the write's transaction, and write handlers that are safe to run twice.
1. Define the Job
A job is a kind, a payload schema, a timeout and a handler that returns an outcome:
// apps/web/jobs/welcome-email.job.tsimport { defineOutboxJob, ok, retry } from '@kit/outbox/server';import { z } from 'zod';import { sendWelcomeEmail } from '#/lib/welcome-email.server.ts';export const welcomeEmail = defineOutboxJob({ kind: 'app.welcome-email', payload: z.object({ userId: z.string() }), timeoutMs: 30_000, async handle({ userId }, ctx) { const result = await sendWelcomeEmail({ userId, signal: ctx.signal }); if (result.rateLimited) { return retry({ code: 'rate_limited', after: 60_000 }); } return ok(); },});kindnames the job in the table and the logs. Prefix your kinds (app.…);kit.…is reserved for jobs the kit adds.payloadis any Standard Schema validator (zod, valibot, arktype). It is checked when you enqueue and again when the job runs.timeoutMsbounds one attempt: past it the attempt counts as timed out (ctx.signalaborts, and a later result is discarded), and the lease that stops two workers running the job is derived from it. Keep it close to the real worst case, and under about 2 minutes: the sweep runs a job itself only iftimeoutMsplus 35 seconds fits its 3-minute budget. Longer jobs (up to 10 minutes) run only through the queue: the sweep re-sends their nudge, so they need the queue binding.handlereturns an outcome; a throw counts asretry({ code: 'unexpected' }). See Failures.
2. List It
Add the job to outboxJobs in apps/web/config/outbox.config.server.ts:
import { welcomeEmail } from '#/jobs/welcome-email.job.ts';import { kitOutboxJobs } from './kit-outbox-jobs.server';export const outboxJobs = [...kitOutboxJobs, welcomeEmail] as const;Only listed kinds are ever claimed, and only listed jobs type-check in enqueue. Keep a job listed until its pending jobs have run: an unlisted kind's jobs wait forever (cancel them first if you remove a job on purpose).
3. Enqueue It With Its Write
import { db } from 'void/db';import { getOutbox } from '#/lib/outbox.server.ts';await getOutbox().transaction(db, async (tx, enqueue) => { const [row] = await tx.insert(user).values(input).returning(); await enqueue(welcomeEmail, { payload: { userId: row.id }, dedupeKey: `welcome:${row.id}`, });});- Pass the top-level
db, never atx. The outbox opens the transaction and nudges the queue after it commits; inside an outer transaction, the nudge would go out before the real commit. - Write through
txin the callback, so your rows and the job commit together. dedupeKeycomes from business identity (welcome:${userId},invoice-paid:${invoiceId}), never a random value: a retried request then finds its job instead of creating a second one, andenqueuereturns{ status: 'exists' }. Keys are permanent, so to do something again on purpose put the reason in the key (reminder:${userId}:${week}).- A refused enqueue throws
OutboxEnqueueError: a payload that fails its schema (or is over 256 KiB), or adedupeKeytaken by another kind. The transaction rolls back, so your write never commits without its job.error.resultsays why.
Optional fields: delayMs (run no earlier than that), tenantKey (an organization id: scopes dedupe keys and operator actions to it), correlationId (a request id, to find related jobs), metadata (passed to the handler as ctx.metadata).
Metadata must be ids-only, just like payloads. /admin/jobs/[id] shows raw metadata to operators with outbox:get. Keep names, email addresses, tokens, secrets and request bodies out of it. The admin renders capped text, but does not redact the stored values.
Inside a Transaction You Don't Own
Better Auth hooks and other libraries open their own transaction. Enqueue in it with getOutbox().enqueue(tx, job, request) (tx must run Drizzle SQL against the same database), and nudge after it commits (in Better Auth, an after hook), or let the sweep run it (up to 5 minutes later):
const job = await getOutbox().enqueue(tx, welcomeEmail, { payload: { userId }, dedupeKey: `welcome:${userId}` });// after the library's transaction has committed:await getOutbox().nudge([job]);Payloads
- Ids, not data. Payloads are stored in
outbox.joband kept for weeks: putuserId, read the user in the handler. Never personal data, tokens or secrets. - Small. Over 256 KiB is refused; put large data in R2 and enqueue its key.
- Change them additively. Jobs already in the table carry the old shape and are validated again when they run: add optional fields, don't rename or remove required ones.
Handlers Run at Least Once
A worker can crash after the work but before the job is marked done, so the same job can run twice. Make each handler safe to repeat:
- Check before you act: read the row, skip if it's already done (
welcomedAtis set). - Pass
ctx.idempotencyKeyto providers that dedupe on a key. - Pass
ctx.signalto every network and database call, so a timed-out attempt stops instead of running alongside its retry. - Never call another service inside a database transaction: do the call, then commit the bookkeeping.
- Read with
void/dbin handlers, like the rest of the app.
ctx also holds jobId, kind, attempt, tenantKey, correlationId and metadata.
Chaining Jobs
A job that enqueues another (the next step) reaches the outbox through ctx.deps.getOutbox(), which every defineOutboxJob job gets:
import { db } from 'void/db';import { z } from 'zod';import { defineOutboxJob, ok } from '@kit/outbox/server';import { sendReceipt } from '#/jobs/send-receipt.job.ts';export const chargeOrder = defineOutboxJob({ kind: 'app.charge-order', payload: z.object({ orderId: z.string() }), timeoutMs: 30_000, async handle({ orderId }, ctx) { // … charge, then hand the receipt to its own job await ctx.deps.getOutbox().transaction(db, (_tx, enqueue) => enqueue(sendReceipt, { payload: { orderId }, dedupeKey: `receipt:${orderId}` }), ); return ok(); },});Splitting long work: stop while ctx.remainingMs() still covers one more step (or check ctx.deadline), then enqueue the rest as the next step. Don't wait for ctx.signal: it aborts only once the attempt has already timed out, and a result after that is discarded (the attempt counts as a timeout and runs again).
Never import getOutbox from lib/outbox.server.ts in a job file. The job list feeds the outbox, so that import is a cycle, and whichever file loads first sees the other undefined. ctx.deps.getOutbox() is typed for any job; enqueueing one missing from outboxJobs throws.
Where Job Files Go
Anywhere; the convention is apps/web/jobs/<name>.job.ts (type-checked and test-included like the rest of the app). That folder isn't one Void scans for bindings, so a binding only a job uses isn't provisioned. Email is already declared (inference: { bindings: { email: true } } in void.config.ts); for another (void/storage, void/kv), declare it the same way or use it from a scanned folder too.