Gerador de Cron para Vercel

Vercel Cron Jobs: invocações agendadas serverless sem dor de cabeça

Vercel Cron Jobs é uma feature da plataforma, lançada em maio de 2023, que dispara periodicamente um endpoint HTTP do seu projeto conforme um cronograma declarado em vercel.json. Em vez de provisionar um servidor com crontab, assinar um SaaS como o Cron-job.org ou montar AWS EventBridge ligado a uma Lambda, você sobe uma função serverless e algumas linhas de configuração — o resto é com a Vercel. O agendamento dispara no instante declarado em UTC (sempre UTC, sem suporte a fuso) e a Vercel emite um HTTP GET regular contra o path que você indicou.

Este gerador produz um bloco crons pronto para colar. Abaixo, uma referência completa sobre sintaxe JSON, limites por plano, padrões de autenticação, código de handler, casos de uso e como o Vercel Cron se compara às alternativas.

A sintaxe do vercel.json

Os crons ficam em um array crons no topo do arquivo. Cada entrada exige um path (a rota da API a invocar) e um schedule (expressão cron padrão de 5 campos):

{
  "crons": [
    { "path": "/api/limpeza", "schedule": "0 3 * * *" },
    { "path": "/api/digest",  "schedule": "*/15 * * * *" }
  ]
}

A expressão segue o formato Unix canônico: minuto hora dia-do-mês mês dia-da-semana. A Vercel não aceita o campo de segundos, o campo de ano do Quartz nem wildcards Quartz como L/W/#. Strings especiais Vixie como @hourly funcionam em alguns casos, mas não estão na documentação — use a forma explícita.

Autenticando a requisição: o padrão CRON_SECRET

Endpoints invocados por cron continuam sendo URLs públicas. Sem auth, qualquer um que adivinhar a rota pode disparar sua rotina de limpeza de um café. A Vercel envia automaticamente um header Authorization: Bearer <CRON_SECRET> quando você define uma variável de ambiente com esse nome exato no projeto. Valide-a na entrada:

// app/api/limpeza/route.ts (Next.js App Router)
export async function GET(request: Request) {
  const auth = request.headers.get('authorization');
  if (auth !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response('Unauthorized', { status: 401 });
  }
  // ... executar o trabalho
  return Response.json({ success: true });
}

Gere o segredo com openssl rand -hex 32 e guarde nas env vars criptografadas da Vercel (Production + Preview). Rotacione como qualquer outro segredo compartilhado.

Limites por plano

• Hobby (gratuito): 2 cron jobs por conta no total, intervalo mínimo de 1 invocação por dia, função limitada a 10 segundos de execução.
• Pro: 40 cron jobs, intervalo mínimo de 1 minuto, função até 60 segundos (ou mais com Fluid Compute).
• Enterprise: limites customizáveis, SLA dedicado, auditoria por add-ons.

As invocações contam contra suas cotas de execução de função e banda, como qualquer outra requisição. Jobs noturnos pesados podem queimar a cota do Hobby surpreendentemente rápido — monitore pelo painel da Vercel.

Casos de uso comuns

• Higiene de banco de dados: apagar sessões expiradas, tokens vencidos, registros marcados como deletados há mais que o prazo de retenção.
• E-mails digest: resumos diários ou semanais montados a partir da atividade do dia anterior.
• Refresh de tokens OAuth: manter integrações de longa duração vivas rotacionando tokens antes de expirar.
• Cache warming: pré-renderizar páginas caras ou puxar dados de terceiros antes que os usuários cheguem.
• Pings de healthcheck: cutucar uma URL externa de monitoramento (UptimeRobot, Better Stack) para confirmar que seu scheduler está vivo.
• Relatórios e rollups analíticos: agregar eventos do dia anterior em tabelas de resumo diário.

Limitações e pegadinhas

• Só UTC: sem configuração de fuso. Para rodar "9h de São Paulo", configure o schedule para 12:00 UTC (BRT é UTC-3) e lembre que o Brasil não observa mais horário de verão.
• Sem retry policy: se seu handler responder 500, a Vercel não tenta de novo. Faça o job idempotente e logue falhas no Sentry ou similar.
• Sem logs dedicados: as invocações aparecem nos logs de função junto com tudo. Pipe para Logtail, Better Stack ou Datadog para observabilidade decente.
• Execução serializada: jobs longos podem sobrepor se o schedule for apertado demais; proteja com lock distribuído (Redis, Upstash) em caminhos críticos.

Alternativas se o Vercel Cron não servir

• GitHub Actions: grátis em repos públicos, intervalo mínimo de 5 minutos, também UTC. Bom quando o agendamento pertence ao pipeline de build.
• Cloudflare Cron Triggers: modelo quase idêntico ao da Vercel, roda Workers em horário programado.
• AWS EventBridge + Lambda: o mais flexível, suporta fuso via sintaxe cron(0 12 * * ? *).
• Cron-job.org: serviço grátis via webhook se você só precisa bater em uma URL e seu app não está na Vercel.
• Inngest, Trigger.dev: schedulers dev-friendly com retry, fan-out e step functions embutidos.

FAQ

Posso configurar fuso diferente de UTC? Não — o agendamento é avaliado sempre em UTC. Calcule o offset para o seu fuso e embuta na expressão. Cuidado com horário de verão em países que ainda o aplicam, pois o offset muda duas vezes ao ano.

Vercel Cron é gratuito? O plano Hobby dá 2 cron jobs sem custo, limitados a uma invocação por dia. Acima disso, Pro (US$ 20/mês por membro) ou Enterprise.

Substitui o Cron-job.org no meu caso? Muitas vezes sim — se o job já mora como função Vercel, manter o agendador dentro da Vercel remove uma peça móvel. Se você orquestra jobs em múltiplos hosts, um agendador externo continua mais simples.

Como testar um cron localmente? A Vercel não executa crons em dev local. Bata no endpoint manualmente com curl -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/limpeza ou use node-cron em script de desenvolvimento.

E se minha função estourar o timeout? A requisição é morta, o job marcado como falho, sem retry. Quebre jobs longos em pedaços menores (pagine, enfileire com QStash/Inngest) ou suba para Pro/Enterprise com timeout maior.