Como Criar um Cron Job em Node.js

TL;DR

Neste tutorial, vamos construir um despertador simples que dispara todos os dias às 7h usando Node.js. Um cron job permite agendar tarefas para rodar automaticamente em horários ou intervalos específicos.

Vamos usar o pacote cron para gerenciar o agendamento. Cron jobs utilizam uma sintaxe específica para definir quando devem rodar — se você nunca usou, o crontab.guru é um ótimo recurso para aprender e testar expressões cron.

Pré-requisitos: Conhecimento básico de Node.js e Express é necessário, pois vamos configurar um servidor simples.

Instalando as Dependências

 yarn add express

 yarn add cron

Configuração do Projeto

Como cron jobs rodam no backend, precisamos de um servidor Node.js. Estou usando Express neste exemplo, mas você pode usar Koa ou qualquer outro framework. Para facilitar, criei um repositório no GitHub com o código completo.

Vamos começar pelo nosso arquivo principal app.js, onde vamos importar e inicializar o cron job:

// app.js

import 'dotenv/config'
import './app/models'

import express from 'express'
import 'express-async-errors'
import cors from 'cors'

import { routes } from './routes'

import jobs from './app/jobs'

import { keys } from './configs/keys'

const port = keys.port || 3001

const app = express()

app.use(cors())
app.use(express.json({}))
app.use(express.urlencoded({ extended: true }))
app.use(routes)

// Jobs
jobs.clock()

app.listen(port, () => {
  console.log(`We are live on ${port}`)
  console.log(`Environment: ${keys.environment}`)
})

Repare na chamada jobs.clock() — ela inicializa nosso cron job de despertador quando o servidor sobe. Vamos entender como isso funciona.

Entendendo a Estrutura do Cron Job

A lógica do cron job fica na pasta jobs/clock. O arquivo principal index.js orquestra tudo importando e configurando os componentes necessários:

import { CronJob } from 'cron'
import moment from 'moment'

import getCronTime from './getCronTime'
import { getJob } from './getJob'
import cronJobCompleted from './cronJobCompleted'
import cronJobShouldStart from './cronJobShouldStart'
import getTimeZone from './getTimeZone'

function clock(): void {
  const job = new CronJob(
    getCronTime(),
    getJob,
    cronJobCompleted,
    cronJobShouldStart(),
    getTimeZone()
  )

  const nextDate = job.nextDate().format('DD/MM/YYYY HH:mm:ss')
  const appStartedAt = moment().format('DD/MM/YYYY HH:mm:ss')

  const loggerPrefix = '[CRON JOB] clock job'

  console.log(`${loggerPrefix} next date: ${nextDate}`)
  console.log(`${loggerPrefix} started at: ${appStartedAt}`)
}

export { clock }

Estamos importando duas bibliotecas externas: cron para agendamento e moment para formatação de datas. Os demais imports são funções auxiliares que vamos criar. Vamos detalhar cada uma.

getCronTime

Esta função define quando o cron job deve rodar:

function getCronTime(): string {
  return '0 7 * * *'
}

export default getCronTime

A expressão cron 0 7 * * * significa "rodar no minuto 0 da hora 7, todos os dias." Você pode usar o crontab.guru para construir e testar suas próprias expressões.

getJob

Esta é a função que executa quando o horário agendado chega. Para nosso exemplo de despertador, ela simplesmente loga uma mensagem:

const getJob = (): void => {
  console.log('ALARM CLOCK RINGING!!!')
}

export { getJob }

Embora este exemplo seja simples, você pode fazer qualquer coisa aqui — enviar e-mails, gerar relatórios, limpar bancos de dados, sincronizar dados com APIs externas, e muito mais.

cronJobCompleted

Este callback roda após o cron job ser concluído. Retornamos null pois não precisamos de nenhuma lógica pós-execução:

function cronJobCompleted(): null {
  return null
}

export default cronJobCompleted

cronJobShouldStart

Isso determina se o cron job deve iniciar automaticamente. Ao retornar true, o job começa assim que é criado. Se retornar false, você precisará chamar .start() manualmente na instância do job:

function cronJobShouldStart(): boolean {
  return true
}

export default cronJobShouldStart

getTimeZone

Isso define o fuso horário para o agendamento do cron. Estou usando o fuso de São Paulo, mas você deve ajustar para as suas necessidades:

function getTimeZone(): string {
  return 'America/Sao_Paulo'
}

export default getTimeZone

Logs e Depuração

Para facilitar a depuração e monitoramento, a função clock inclui logs que mostram quando o job iniciou e quando vai rodar novamente:

const nextDate = job.nextDate().format('DD/MM/YYYY HH:mm:ss')
const appStartedAt = moment().format('DD/MM/YYYY HH:mm:ss')

const loggerPrefix = '[CRON JOB] clock job'

console.log(`${loggerPrefix} next date: ${nextDate}`)
console.log(`${loggerPrefix} started at: ${appStartedAt}`)

Isso é útil para verificar que o cron job está configurado corretamente e saber exatamente quando ele vai executar em seguida.

Conclusão

É isso! Você agora tem um cron job funcionando em Node.js. Esta estrutura modular facilita adicionar mais tarefas agendadas — basta criar uma nova pasta com o mesmo padrão e chamá-la no arquivo principal da aplicação.

Cron jobs são incrivelmente úteis para automatizar tarefas repetitivas como envio de e-mails agendados, geração de relatórios, limpeza de dados antigos ou sincronização com serviços externos. Fique à vontade para conferir o código completo no GitHub e adaptá-lo às suas necessidades.