Cron

A cron job is a named handler with a cron expression, declared by a plugin. VitNode stores each job in the core_cron table, decides when it is due, and lists it in the AdminCP. In this guide the site-notes plugin gets a nightly job, and you run it once from the Debug Panel.

Before you beginCopy Anchor Link

• The site-notes plugin with its notes module and site_notes table, from the beginner path up to Database. Any plugin with a top-level API module works the same way.
• Something that ticks the cron endpoint once a minute: the node-cron adapter on a long-lived server, or an external scheduler. Without one, jobs are registered but never run on their own. Run Job Now in the Debug Panel still works.

Add a cron jobCopy Anchor Link

import { buildCron } from '@vitnode/core/api/lib/cron'
import { count } from 'drizzle-orm'

import { site_notes } from '@/database/notes'

export const countNotesCron = buildCron({
  name: 'count-notes',
  description: 'Log how many site notes exist, every night at 03:00',
  schedule: '0 3 * * *',
  handler: async c => {
    const [{ total }] = await c
      .get('db')
      .select({ total: count() })
      .from(site_notes)

    await c.get('log').debug(`site-notes holds ${total} notes`)
  },
})

import { buildModule } from '@/api/builders'
import { countNotesCron } from '@/api/cron/count-notes.cron'

import { listNotesRoute } from './routes/list.route'
import { showNoteRoute } from './routes/show.route'

export const notesModule = buildModule({
  name: 'notes',
  routes: [listNotesRoute, showNoteRoute],
  cronJobs: [countNotesCron], 
})

Check the resultCopy Anchor Link

1. Open Debug Panel → Cron & queue (/admin/core/debug/cron). The table has a count-notes row with plugin site-notes and the status Waiting for first run.
2. Press the play button on that row (Run Job Now).
3. Open Debug Panel → Log explorer (/admin/core/debug/logs). A new debug entry reads site-notes holds 3 notes (or however many you have). The entry's plugin is @vitnode/core, for the reason explained in the next section.

What a job's context gives youCopy Anchor Link

A job runs inside core's cron request, not inside one of your routes:

• c.get('db'), c.get('log'), c.get('queue') and c.get('cache') work as in a route. There is no signed-in user.
• c.get('plugin') is @vitnode/core, so logs are tagged with core. A queue task still belongs to the plugin that defines it, so c.get('queue').dispatch(announceNoteTask, { noteId }) stores the row under site-notes, and a cache entry is stored under the plugin that defines it. An event emitted here records @vitnode/core as its emitter unless you pass { pluginId: manifest.id } to emit().
• All jobs that are due on a tick run at the same time.
• The schedule is only as precise as the tick. With a tick every minute, */10 * * * * * (every 10 seconds) still runs once a minute.

Choose what ticks the clockCopy Anchor Link

The API runs no timer by default. Every cron run starts with a POST /api/@vitnode/core/cron that carries Authorization: Bearer <CRON_SECRET>, and that endpoint runs whatever is due.

Pick one. Two tickers do no harm, since each due run is claimed once, but they double the requests for nothing.

Manage cron jobs in the Debug PanelCopy Anchor Link

Open Debug Panel → Cron & queue in the AdminCP (/admin/core/debug/cron), or type "Cron jobs" into the ⌘K admin search. Viewing it needs the cron → can_view staff permission.

• The table lists every job with its Name, Plugin and Time: the schedule, a status badge, and the last and next run. It is sorted by next run, with a search box to find a job.
• The play button on a row (Run Job Now) runs that job on demand. It needs the cron → can_run permission.

Health warningsCopy Anchor Link

Cron fails quietly by nature: nobody notices a job that didn't run. So VitNode watches for it.

A job is overdue when its next scheduled run is more than 15 minutes in the past. Never-run jobs count from the moment they were registered.

The scheduler card at the top of the section sums it up:

Next to it you get the last run, the next run and how many jobs are registered. The table below lists every job with an Overdue, On schedule or Waiting for first run status.

The same check powers the Debug Panel Overview and the Cron Jobs and Queue Tasks cards at Core → System → Integrations.

Jobs must be idempotentCopy Anchor Link

A job can run more often than its schedule suggests, so write handlers that are safe to run twice:

• A failed run is retried. When a handler throws, VitNode hands the run back and the next tick runs it again, including whatever the first attempt already did.
• Runs can overlap. Each due run is claimed by exactly one tick, even with several instances, but nothing waits for the previous run to finish. A job scheduled every minute that takes three minutes runs alongside itself.
• A new job is not claimed yet on the very first tick after it is registered, so every instance that ticks at that moment runs it.

Record what you processed and skip it next time, for example with a processedAt column or a queue task with a dedupeKey. Move slow work into the queue. A cron handler should take seconds, not minutes.

buildCron optionsCopy Anchor Link

RelatedCopy Anchor Link