vercel-cron-runner

Runs Vercel cron jobs for self-hosted Next.js apps. Reads cron settings from CRON_CONFIG, vercel.json, or vercel.ts and triggers endpoints on schedule.

Install

npm install vercel-cron-runner

Usage

BASE_URL=http://localhost:3000 npx vercel-cron-runner

By default, the runner reads vercel.json from the current working directory and schedules HTTP requests to your app based on the crons config.

Environment variables

| Variable | Required | Description | |---|---|---| | BASE_URL | Yes | Origin of your app, without credentials, a path, query, or fragment (e.g. http://localhost:3000) | | CRON_SECRET | No | Sent as Authorization: Bearer <secret> header | | CRON_CONFIG | No | Cron configuration as plain JSON, using the same shape as vercel.json | | CONFIG_PATH | No | Path to directory containing vercel.json (defaults to cwd) | | REQUEST_TIMEOUT_MS | No | Positive integer HTTP request timeout in milliseconds (defaults to 300000) |

When CRON_CONFIG is set, it takes precedence over vercel.json and vercel.ts. This allows the runner to be deployed without access to the application's files:

BASE_URL=https://app.example.com \
CRON_CONFIG='{"crons":[{"path":"/api/sync","schedule":"*/5 * * * *"}]}' \
npx vercel-cron-runner

For larger configurations, continue using vercel.json, vercel.ts, or a mounted configuration file with CONFIG_PATH to avoid shell escaping and environment variable size limits.

Local development

Run cron jobs locally alongside your dev server:

BASE_URL=http://localhost:3000 npx vercel-cron-runner

Example vercel.json

{
  "crons": [
    {
      "path": "/api/sync",
      "schedule": "*/5 * * * *"
    },
    {
      "path": "/api/cleanup",
      "schedule": "0 0 * * *"
    }
  ]
}

Schedules use Vercel's five-field cron syntax and always run in UTC. Named months or weekdays, six-field schedules, and schedules that restrict both day of month and day of week are not supported.

Docker

Run the cron runner in a dedicated container or service alongside your Next.js app. If the production image uses Next.js standalone output or prunes dependencies, the binary might not be present. In that case, explicitly install it in the cron image. The runner container also needs the project's vercel.json:

FROM node:24-alpine

WORKDIR /app
COPY vercel.json ./
RUN npm install --global vercel-cron-runner

ENV BASE_URL=http://app:3000

CMD ["vercel-cron-runner"]

License

MIT