workflow-cron-start

Start Vercel Workflows on a cron schedule using cronStart() and a build-time wrapper pipeline.

What this does

• cronStart(workflow, args, options) — schedules a workflow on a cron expression. Calls are rewritten at build time to run a generated “scheduler” workflow (cron sleep → run your workflow → repeat).
• cronEnd(runId) — cancels a run started with cronStart.
• Next.js — use withCronWorkflow in next.config (instead of withWorkflow alone) so the loader can transform cronStart() and Turbopack matches files that only import cronStart (no "use workflow" in the same file).

Next.js setup (required)

// next.config.ts
import type { NextConfig } from "next"
import { withCronWorkflow } from "workflow-cron-start/next"

const nextConfig: NextConfig = { /* … */ }

export default withCronWorkflow(nextConfig)

Peer dependencies: next and workflow.

Installation

npm install workflow-cron-start

Quick start

// app/api/run-report/route.ts
import { cronStart } from "workflow-cron-start"
import { sendReport } from "@/workflows/send-report"

export async function POST() {
  const run = await cronStart(sendReport, ["weekly"], {
    cron: "0 9 * * *",
    timezone: "America/New_York",
  })
  return Response.json({ runId: run.runId })
}

Your workflow module should use "use workflow" as usual; cronStart wires it to the generated cron wrapper.

API

cronStart(workflow, args, options)

| Argument | Description | |----------|-------------| | workflow | The workflow function to run on each tick | | args | Tuple of arguments passed to the workflow each time | | options | CronOptions (see below) |

Returns Promise<CronStartResult> with runId.

cronEnd(runId)

Cancels a cron scheduler run previously returned from cronStart.

CronOptions

| Property | Type | Required | Description | |----------|------|----------|-------------| | cron | string | Yes | Cron expression | | timezone | string | No | IANA zone (recommended) | | onError | "continue" | "stop" | No | Default "continue" |

Re-exports

cronSleep / CronSleepOptions from workflow-cron-sleep (used by generated code).

Timezone

If you omit timezone, behavior follows the generated scheduler and your deployment environment. For predictable schedules, set an explicit IANA timezone.

Error handling

Use onError: "stop" in CronOptions if the cron loop should stop when the inner workflow throws; default is "continue".

Cron expression reference

| Expression | Meaning | |------------|---------| | 0 9 * * * | Every day at 9:00 AM | | 30 8 * * 1 | Every Monday at 8:30 AM | | 0 0 1 * * | First day of month at midnight | | 0 */2 * * * | Every 2 hours | | 0 9 * * 1-5 | Weekdays at 9:00 AM |

Troubleshooting

If you see cronStart() was not transformed at build time, confirm withCronWorkflow wraps your Next config and restart the dev server or rebuild.

Requirements

• workflow (Vercel Workflows SDK)
• next (for workflow-cron-start/next and the loader)
• workflow-cron-sleep (dependency of this package)

License

MIT