Skip to Content

Scheduled jobs

≈ 10 min · you will have a scheduled job (cancel stale orders every hour, send a report every morning) that is safe to re-run.

A cron job is a function that manh.run calls on a schedule, with nobody opening the app. Every file ending in .cron.ts is one job; the file name is the job name.

1. Create the job file

The file exports two things: schedule (5-field cron syntax, in UTC) and a default async function. The function doesn’t return a response.

app/orders/ ├── repository.ts └── cancel-stale.cron.ts job "cancel-stale", runs every hour
app/orders/cancel-stale.cron.ts
import { cancelStalePending } from "./repository"; export const schedule = "0 * * * *"; // minute 0 of every hour export default async function () { const n = await cancelStalePending(Date.now() - 24 * 3600 * 1000); console.log(JSON.stringify({ job: "cancel-stale", cancelled: n })); }

The job calls a repository function the same way a handler does, so the cancellation rule lives in one place.

2. Convert local time to UTC

Schedules use UTC. Vietnam is UTC+7, so subtract 7 hours from Vietnam time.

  • 08:00 every day → 0 1 * * *
  • 18:00 every day → 0 11 * * *
  • 09:00 Monday to Friday → 0 2 * * 1-5
  • Every 15 minutes → */15 * * * *
  • 07:00 on the 1st of every month → 0 0 1 * *

Day of week: 0 or 7 is Sunday, 1 is Monday. When you restrict both day of month and day of week, the job runs when either matches. The shortest interval is 1 minute.

3. Process only what’s new

The function receives { lastRunAt, scheduledAt }. lastRunAt is the last successful run (undefined the first time), so you don’t need to store your own checkpoint.

app/reports/daily-digest.cron.ts
import { email } from "manh/email"; import { salesSince, managerEmails } from "./repository"; export const schedule = "0 1 * * *"; // 08:00 Vietnam time export default async function ({ lastRunAt, scheduledAt }: { lastRunAt?: Date; scheduledAt: Date }) { const since = lastRunAt ?? new Date(scheduledAt.getTime() - 86_400_000); // first run: last 24 hours const s = await salesSince(since); for (const to of await managerEmails()) { await email({ to, subject: `Sales since ${since.toLocaleDateString("en-GB")}`, html: `<meta charset="utf-8"><p>${s.count} orders · ${s.revenue.toLocaleString("vi-VN")} đ</p>`, }); } }

4. Make the job safe to re-run

A failed run (thrown error, 5xx, timeout) is retried, up to 3 attempts (30 seconds, then 60 seconds later). So the job must be idempotent: running it twice has the same result as running it once.

app/orders/repository.ts
// import { db, eq, and, lt } from "app/db"; … export async function cancelStalePending(before: number) { const rows = await db.update(orders) .set({ status: "cancelled" }) .where(and(eq(orders.status, "pending"), lt(orders.createdAt, before))) // only orders still pending .returning({ id: orders.id }); return rows.length; }

The status = "pending" condition means a second run never touches orders that are already cancelled.

5. Monitor and run by hand

Open Operations › Cron in the project to see run history, pause a job or click Run now. Your agent can do the same through MCP.

Good to know

  • A job skips middleware.ts and has no c or user. Pass in what the job needs.
  • A run gets 30 seconds of CPU. For longer work, split it up or move it to a background job.
  • If the previous run of the same job is still going, the next tick is skipped.
  • The number of jobs per app depends on your plan (see Plan limits).

Next steps

Last updated