Task Scheduling
Every app has chores: delete expired API tokens every night, send a weekly digest on Monday morning, clean up half-finished uploads every hour. The scheduler lets you write that timetable in your code, next to everything else, instead of in a server’s cron file that nobody remembers.
It works like Laravel’s: the server runs one command every minute (node strut schedule:run), and that command checks your timetable and starts whatever is due (whose time has come). Each entry in the timetable is a scheduled task: a node strut command, a queued job, or a small function.
The smallest example
Section titled “The smallest example”Step 1: write the timetable. Delete expired personal access tokens every night:
import { defineSchedule } from '@strutvane/framework'
export default defineSchedule((schedule) => { schedule.command('tokens:prune').daily()})Step 2: check it.
node strut schedule:listWhat you’ll see:
0 0 * * * node strut tokens:prune ............ Next due: in 13 hours (2026-11-16 00:00 Europe/Berlin)Step 3: run it. In development, npm run dev runs the scheduler for you. On a server, you add one line to cron (see Running the scheduler on a server). At midnight:
[2026-11-16 00:00:00] production.INFO: Running scheduled command: tokens:prune[2026-11-16 00:00:00] production.INFO: Deleted 14 expired personal access tokens.What you can schedule
Section titled “What you can schedule”A node strut command
Section titled “A node strut command”Any command, with its arguments, exactly as you’d type it:
import { defineSchedule } from '@strutvane/framework'
export default defineSchedule((schedule) => { schedule.command('tokens:prune').daily() schedule.command('auth:clear-resets').hourly() // expired reset tokens, email links, invitations schedule.command('storage:prune-temp').everyThirtyMinutes() schedule.command('model:prune').dailyAt('02:30') // models marked prunable()})These four are the usual housekeeping chores. tokens:prune and auth:clear-resets come with the auth package; model:prune deletes rows your models mark as prunable (for example, soft-deleted posts older than a year); storage:prune-temp removes uploads that were never finished.
Your own command
Section titled “Your own command”Write the command with defineCommand (see Console Commands), then schedule it by name:
import { defineCommand } from '@strutvane/framework'
export default defineCommand({ name: 'digest:weekly', description: 'Mail every author a summary of last week', async run({ output }) { // find authors, build and queue their digests output.line('Queued 37 digests.') },})import { defineSchedule } from '@strutvane/framework'
export default defineSchedule((schedule) => { schedule.command('digest:weekly').weeklyOn(1, '08:00') // Mondays at 08:00})A queued job
Section titled “A queued job”Schedule a job to put it on the queue at the right time. The scheduler only dispatches it; a worker runs it, with retries:
import { defineSchedule } from '@strutvane/framework'import { SyncPartnerPrices } from '../app/jobs/sync-partner-prices.ts'
export default defineSchedule((schedule) => { schedule.job(new SyncPartnerPrices({ partnerId: 'acme-wholesale' })).everyFifteenMinutes()})Prefer this for anything slow or that talks to other services: the scheduler stays quick, and failures get the queue’s retries and failed-jobs list.
A small function
Section titled “A small function”For a few lines that don’t deserve a command, schedule a function, and give it a name (it’s what schedule:list and the logs show):
import { defineSchedule, Log } from '@strutvane/framework'import { Post } from '../app/models/post.ts'
export default defineSchedule((schedule) => { schedule .call(async () => { const drafts = await Post.query().where('status', 'draft').count() Log.info('Draft posts waiting', { drafts }) }) .name('count-drafts') .hourly()})How often: frequencies
Section titled “How often: frequencies”| Method | Runs |
|---|---|
everyMinute() |
every minute |
everyFiveMinutes(), everyFifteenMinutes(), everyThirtyMinutes() |
every 5, 15 or 30 minutes |
hourly() |
at minute 0 of every hour |
daily() |
at midnight |
dailyAt('02:30') |
every day at 02:30 |
weekdays() |
Monday to Friday (combine with another, e.g. .weekdays().dailyAt('09:00')) |
weeklyOn(1, '08:00') |
every Monday at 08:00 (0 = Sunday) |
monthly() |
on the 1st, at midnight |
cron('0 3 * * 1') |
any cron expression: minute, hour, day of month, month, day of week |
A cron expression is five fields that describe when to run: 0 3 * * 1 reads “minute 0, hour 3, any day of the month, any month, Monday”, so every Monday at 03:00.
Time zones
Section titled “Time zones”Times are read in your app’s time zone (the one the installer asked for in question 21) unless you say otherwise:
schedule.command('digest:weekly').weeklyOn(1, '08:00').timezone('America/New_York')Only in some environments
Section titled “Only in some environments”schedule.command('reports:send-to-partner').daily().environments(['production'])Your laptop then never mails a partner by accident.
Never twice at the same time: withoutOverlapping
Section titled “Never twice at the same time: withoutOverlapping”If a task can take longer than its interval (a 15-minute sync that sometimes takes 20), the next run could start while the last one is still going. withoutOverlapping() skips the new run until the old one has finished:
schedule.command('partners:sync').everyFifteenMinutes().withoutOverlapping()What you’ll see when a run is skipped:
local.INFO: Skipping scheduled command partners:sync: the previous run is still going.It uses a cache lock with a lifetime, so a crashed run doesn’t block the task forever: the lock frees itself after its lifetime. The default lifetime isn’t decided yet; you can pass one in minutes: withoutOverlapping(30).
Only on one server: onOneServer
Section titled “Only on one server: onOneServer”With three web servers each running schedule:run, a daily task would run three times. onOneServer() lets only the first server that grabs the task run it:
schedule.command('digest:weekly').weeklyOn(1, '08:00').onOneServer()What you’ll see: the digest goes out once. The other two servers log that another server took it.
Hooks: before, after, success and failure
Section titled “Hooks: before, after, success and failure”Run code around a task, for example to alert someone when the weekly digest fails:
import { defineSchedule, Log } from '@strutvane/framework'
export default defineSchedule((schedule) => { schedule .command('digest:weekly') .weeklyOn(1, '08:00') .before(() => Log.info('Weekly digest starting')) .onSuccess(() => Log.info('Weekly digest finished')) .onFailure(() => Log.critical('Weekly digest FAILED')) .after(() => Log.info('Weekly digest task done, whatever the result'))})What you’ll see when digest:weekly exits with a non-zero code:
production.INFO: Weekly digest startingproduction.ERROR: Scheduled command failed: digest:weekly (exit code 1)production.CRITICAL: Weekly digest FAILEDproduction.INFO: Weekly digest task done, whatever the resultRoute critical messages to Slack in config/logging.ts and someone hears about it at once (see Logging). A failing task never stops the other tasks that were due in the same minute.
Running the scheduler
Section titled “Running the scheduler”In development
Section titled “In development”npm run dev starts the scheduler with your app (packages register extra processes, like Laravel’s composer run dev). To run it on its own, in the foreground:
node strut schedule:workWhat you’ll see: it wakes up every minute and runs whatever is due, until you press Ctrl+C.
To run whatever is due right now, once (handy when testing a new task):
node strut schedule:runRunning the scheduler on a server
Section titled “Running the scheduler on a server”On a server, cron (or your platform’s equivalent) runs schedule:run every minute. That’s the only cron entry your app ever needs.
Linux and macOS (crontab -e as the user that owns the app):
* * * * * cd /var/www/my-app && node strut schedule:run >> /dev/null 2>&1The output goes nowhere because the scheduler writes its own log file in storage/logs/.
Windows (Task Scheduler): create a task that runs every minute, with:
Program: nodeArguments: strut schedule:runStart in: C:\apps\my-appContainers (Kubernetes, ECS, Fly…): run one extra container from the same image with the command node strut schedule:work, next to your web and worker containers. Run exactly one replica of it, or use onOneServer() on every task, so tasks don’t run once per copy.
A PaaS: use its cron or scheduler feature to run node strut schedule:run every minute, or a worker process running schedule:work.
Knowing it really runs
Section titled “Knowing it really runs”A scheduler that silently stopped is worse than none: nobody notices the nightly clean-up stopped. @strutvane/queue-dashboard adds a Schedules tab (last run, next run, result of each task) and a health check that fails when a task missed its run, which @strutvane/health can alert on.
With Docker or without Docker
Section titled “With Docker or without Docker”- With Docker, the scheduler runs inside the
appcontainer.npm run devstarts it there;node strut schedule:listorschedule:runtyped on your computer is forwarded into the container. You don’t install cron on your computer. - Without Docker,
npm run devruns it on your machine; for a long-running setup use cron (Linux, macOS) or Task Scheduler (Windows) as above. - Logs: the scheduler writes its own file in
storage/logs/(each extra process gets its own file, so lines never mix).node strut log:tailmerges it with the others.
Common mistakes
Section titled “Common mistakes”My task never runs on the server
Section titled “My task never runs on the server”Why: nothing calls schedule:run. Declaring a task in routes/console.ts only writes the timetable.
Fix: add the cron line (or the container / Task Scheduler entry), then check:
node strut schedule:listMy task runs three times
Section titled “My task runs three times”Why: three servers (or three container replicas) each run the scheduler, and the task isn’t limited to one. Fix:
schedule.command('digest:weekly').weeklyOn(1, '08:00').onOneServer()or run exactly one scheduler container.
onOneServer() doesn’t stop duplicates
Section titled “onOneServer() doesn’t stop duplicates”Why: each server uses its own non-shared cache, so each one “wins” the lock.
Fix: point every server at the same cache store (the same database, or the same REDIS_URL).
The task ran an hour early (or late)
Section titled “The task ran an hour early (or late)”Why: the server’s time zone or a daylight saving switch differs from what you expected. Fix: set the time zone on the task, and avoid times inside the switch:
schedule.command('reports:daily').dailyAt('06:00').timezone('Europe/Berlin')A long task stops other tasks
Section titled “A long task stops other tasks”Why: slow work runs inside the scheduler process itself. Fix: schedule a queued job instead of the slow code, so the scheduler only dispatches it:
schedule.job(new SyncPartnerPrices({ partnerId: 'acme-wholesale' })).everyFifteenMinutes()A task is “skipped: the previous run is still going” forever
Section titled “A task is “skipped: the previous run is still going” forever”Why: a run crashed while holding the overlap lock, and the lock hasn’t expired yet. Fix: wait for the lock’s lifetime, or give it a shorter one that’s still longer than a normal run:
schedule.command('partners:sync').everyFifteenMinutes().withoutOverlapping(30)Next steps
Section titled “Next steps”- Queues: run the slow part of a scheduled task in the background.
- Console Commands: write your own
node strutcommands. - Cache: the locks behind
withoutOverlappingandonOneServer. - Deployment: where the scheduler runs in production.