How to use Cloudflare Scheduled Workers in Base

Some work is not triggered by a request. It runs on a clock: clean up expired sessions every hour, send a digest every morning, recompute an aggregate every few minutes. Cloudflare calls these scheduled workers, and they fire on a cron schedule rather than on an incoming request. Base models the unit of scheduled work as an executable, and you register it with a cron expression in one place.

A scheduled executable

The thing that runs on a schedule is an executable: a class that does a unit of work when called. You mark it as a scheduled executable and, when you want it to run on a clock, you give it a cron expression. The cron expression is validated when you register it, so a typo in your schedule fails loudly at startup instead of silently never running. That early failure is the kind of thing you want from a framework: the mistake surfaces when you make it, not three weeks later when someone notices the digest never went out.

A scheduled executable receives a context when it runs, the same way a request handler receives a request context. From inside it you have dependency injection, so the executable can reach a database, a queue, an object store, anything a normal handler can reach. Scheduled work is just work in a worker, started by the clock instead of by a request.

Registering schedules

You register your scheduled executables in your worker settings, in the scheduled block. You list the executables that can be scheduled, and you can set how many are allowed to run concurrently. The default is one at a time, which is the safe default: scheduled work often touches shared state, and running schedules one after another avoids two runs stepping on each other. Raise the concurrency when your scheduled work is independent and you want it to run in parallel.

There is a second, quieter form. An executable can be marked as schedulable without a fixed cron, so a module can wire it up later with a schedule supplied by configuration. This is how a reusable module ships a scheduled job without hard-coding when it runs, and lets the worker that uses the module decide the cadence.

Scheduled work and durable objects share a clock

The same scheduled machinery powers two triggers. One is the Cloudflare cron trigger, the platform-level clock that fires your worker on a schedule. The other is a durable object alarm: a durable object can set an alarm to wake itself later, and that wake-up flows through the same scheduled path. So the model you learn for cron-triggered work is the same model that handles a durable object asking to be woken at a specific time. One concept, two ways of starting it.

When to reach for a scheduled worker

Reach for a scheduled worker for anything that should happen on a cadence rather than in response to a user: cleanups, digests, periodic syncs, recomputed aggregates. If the work is heavy, consider having the scheduled executable enqueue messages rather than do everything inline, so the schedule stays a trigger and a queue does the chewing. The scheduled worker is the clock; let it ring, and let the rest of your worker do the work.

The mental model to keep

A scheduled worker in Base is an executable that runs on a clock: mark a class as a scheduled executable, give it a validated cron expression, register it in your scheduled settings, and it fires on Cloudflare's cron trigger. Control parallelism with the concurrency setting, default to one at a time when runs share state, and remember the same path also handles durable object alarms.