kb-cron-jobs

What problem does it solve?

kb-cron-jobs solves the recurring issue of cron drift, brittle Vercel configuration, silent failures, and inconsistent operational behavior in Next.js projects by providing a single, portable end-to-end pattern for declaring, validating, running, and monitoring cron jobs.

Core Features & Use Cases

• SSOT job registry for crons: Define jobs once (id, path, schedule, handler, runtime knobs like maxDuration, retry, notification policy) and derive everything else from that registry.
• Autogenerated vercel.json with drift defense: Generate deterministic cron entries from the registry and validate that the on-disk vercel.json matches (fail on manual edits).
• Pre-commit linter with actionable guardrails: Validate id format, route existence, handler export naming, cron format, orphans, maxDuration drift, and Vercel JSON shape via a vendored schema/supplemental allowlist.
• Secure cron runtime contract: Enforce CRON_SECRET Authorization, require force-dynamic, and align handler time budgets with the registry.
• Operational run tracking + structured logging: Persist job runs to a DB table and emit both structured logs and auditable run history.
• Resilience and observability patterns: Implement runWithRetry, stale-log cleanup, consolidated watchdog meta-cron for misses/failures, and idempotency contracts.
• Admin-controlled execution: Provide manual “run now” invocation from an admin UI that uses the same handler as scheduled crons, plus on/off toggles via DB flags (not registry removal).
• Portability beyond Vercel: Keep the registry portable while swapping the generator for other platforms (Render, Railway, self-hosted queues).

Quick Start

Use the kb-cron-jobs skill to add your first cron by creating a single registry entry in src/config/cron-jobs.ts, generating vercel.json from it, wiring a cron route under src/app/api/cron/.../route.ts following the handler conventions, and enabling the admin “run now” + watchdog coverage so failures and missed runs become visible and actionable.