Cron Jobs

A cron job in VitNode consists of a named handler and a standard 5-field cron expression. Cron definitions are automatically registered in the core_cron database table and manageable through the AdminCP.

Quick start

1. Define a Cron Job

Create a cron definition in your plugin:

import { buildCron } from "@vitnode/core/api/lib/cron"

export const cleanupCron = buildCron({
  name: "cleanup-drafts",
  description: "Remove expired post drafts every midnight",
  schedule: "0 0 * * *", // Standard cron syntax
  handler: async (c) => {
    await c.get("log").info("Running midnight cleanup...")
  },
})

2. Register in an API Module

Attach the cron job to a module in src/api/modules/:

import { buildModule } from "@vitnode/core/api/lib/module"
import { cleanupCron } from "../../cron/cleanup.cron"

export const postsModule = buildModule({
  name: "posts",
  routes: [listPostsRoute],
  cronJobs: [cleanupCron], 
})

When your plugin is mounted in config.api.ts, the cron job is automatically registered.

Execution Adapters

VitNode does not hold persistent timers in the HTTP worker. Instead, jobs are triggered via an adapter:

Option A: In-Process Node CRON (Single Server)

Best for single-instance or local development. Configure in vitnode.api.config.ts:

import { NodeCronAdapter } from "@vitnode/core/api/adapters/cron/node-cron"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  cron: {
    adapter: NodeCronAdapter(), 
  },
})

Option B: External Webhook (Multi-Instance / Serverless)

Trigger runs via external HTTP schedulers (AWS EventBridge, GitHub Actions, or crontab):

curl -X POST https://your-domain.com/api/@vitnode/core/cron   -H "Authorization: Bearer $CRON_SECRET"

AdminCP Management

Manage and inspect cron jobs in the AdminCP at Core → Advanced → Cron Jobs (/admin/core/advanced/cron):

• View status, schedules, and last execution logs.
• Click Run Now to execute any job manually on demand.

buildCron Options

Learn More