Background jobs

Background jobs let your application accept work now and process it separately from the request a customer is waiting for. Use them for notifications, file processing, report generation, or data synchronization while keeping the app responsive.

Edge Kit connects Cloudflare Queues to your application with typed jobs, a producer, a consumer, and processing logs. Both sending and processing run within the same Worker deployment.

Job lifecycle

A report export visualization above illustrates the flow:

1. Request: a customer asks for a report. The Worker checks access, creates a report record, and submits a typed job.
2. Queue: Cloudflare holds the message until delivery, including an optional delay. The app can respond once submission succeeds.
3. Processing: the Worker consumer loads the current data from D1, generates the report, and saves the file in R2.
4. Completion: the handler updates the report's status and acknowledges the message. A processing failure is logged and retried.

The producer and consumer belong to the same Worker deployment, but run in separate executions. The customer does not need to keep the original request open while the job completes.

Application workflows

The kit supplies the typed job registry, producer connection, consumer dispatch, and processing logs. Your handler supplies the work, such as a report export, file processing, or a localized notification email.

Keep each handler within the Workers execution limits. Use batching or a dedicated processing service for heavier workloads.

Job state

For customer-visible progress, store a status such as pending, ready, or failed in your application data. A queue message carries the request; the product record lets the UI show the outcome and offer recovery.

Payloads

Keep messages small and focused on the work to perform. Record identifiers, the intended operation, and a recipient locale are often enough. The handler can load current records rather than carrying a large copy of the customer's data through the queue.

After registering a report handler, its producer could schedule work like this:

import { env } from "cloudflare:workers";

await env.QUEUE.send(
  {
    job: "generate-report",
    payload: { reportId, locale },
  },
  { delaySeconds: 60 },
);

generate-report is an example job you add, with a matching registry entry and handler. Its payload refers to the report record; the handler loads the data and writes the result when processing begins after the delay.

That current-state check matters when processing is delayed. A customer might delete the resource, change their address, or lose access before the task runs. Decide which of those changes should cancel the work and which values should remain a snapshot of the original request.

Avoid including credentials or full private documents in payloads. Besides increasing message size, they can end up in operational diagnostics. Use references to the appropriate server-side integration or storage record instead.

Delivery

For work that should happen once, track a stable job key or use the destination provider's idempotency support: repeating the same request should not repeat its effect. Retry limits and a dead-letter queue let you retain failed messages for investigation when your workflow needs that policy.

Cloudflare's delivery guarantees and consumer configuration explain these controls.

Not every failure benefits from another attempt. A temporary provider outage can recover on retry; a deleted resource or invalid destination may need the handler to finish without repeating the same impossible operation. Record enough context to distinguish those outcomes.

If the handler creates an external resource, use the provider's idempotency mechanism where available. A local completed marker alone can miss a failure that happens after the external action succeeds but before the marker is saved.

Welcome email example

The included welcome message demonstrates delayed processing. After verification or creation of an already verified account, the app queues a message with a five-minute delay. Its handler checks the customer's current record and verification state before sending.

Use this flow as a reference for another job's payload, delay, database access, and email delivery. It also shows how a handler can skip work that is no longer relevant.

Development and deployment

Wrangler configuration connects the producer and consumer to the queue. Deployment covers creating the production resource; local development provides a separate queue simulation.

Check a successful task, a missing record, and a temporary processing error when adding a handler. Observability covers processing logs and retries.