Cron Scheduler Expert

Cron & Scheduler Expert (2026 Edition)

English | Bahasa Indonesia

English

Orchestration & Integration

• Upstream Triggers & Workflows: async-queue-temporal-expert, event-driven-architect, js-backend-expert
• Cloud & Edge Platforms: cloud-hosting-expert, cloudflare-workers-expert
• Domain Consumer Jobs: saas-billing, email-notification-expert, data-pipeline-etl-expert
• Locking & Observability: database-orm-expert, data-telemetry-expert, logging-error-tracking-expert
• Lifecycle & Governance: zero-to-prod-orchestrator, session-memory-manager

Description

Production-grade guide for implementing scheduled tasks, cron jobs, and recurring background work in modern web applications. Covers Vercel Cron Jobs, Cloudflare Workers Cron Triggers, Inngest scheduled functions, node-cron, BullMQ repeatable jobs, distributed cron locking (Redis-based), timezone-aware scheduling, and common use cases (cleanup jobs, report generation, health checks, subscription renewals).

Trigger Conditions

Activate this skill when:

• Setting up scheduled/recurring tasks (daily reports, cleanup, health checks).
• Configuring Vercel Cron Jobs or Cloudflare Workers Cron Triggers.
• Implementing subscription renewal checks or billing cycle jobs.
• Building data aggregation or ETL pipelines on a schedule.
• Needing distributed cron locking to prevent duplicate execution.
• Scheduling email digests or notification batches.

Platform Selection Guide

Recommendation: Use Vercel Cron for Next.js apps on Vercel. Use Inngest for complex multi-step scheduled workflows. Use BullMQ repeatable jobs for self-hosted environments.

1. Vercel Cron Jobs

jsonCopy code
// vercel.json
{
  "crons": [
    {
      "path": "/api/cron/daily-cleanup",
      "schedule": "0 3 * * *"
    },
    {
      "path": "/api/cron/hourly-health-check",
      "schedule": "0 * * * *"
    },
    {
      "path": "/api/cron/weekly-report",
      "schedule": "0 9 * * 1"
    }
  ]
}

typescriptCopy code
// app/api/cron/daily-cleanup/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  // Verify the request is from Vercel Cron (not public)
  const authHeader = request.headers.get('authorization');
  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  try {
    // Cleanup expired sessions
    const deletedSessions = await db.delete(sessions)
      .where(lt(sessions.expiresAt, new Date()));

    // Cleanup orphaned uploads (older than 24h, not linked to any record)
    const deletedUploads = await db.delete(uploads)
      .where(and(
        isNull(uploads.linkedRecordId),
        lt(uploads.createdAt, new Date(Date.now() - 86400000)),
      ));

    return NextResponse.json({
      ok: true,
      cleaned: { sessions: deletedSessions.rowCount, uploads: deletedUploads.rowCount },
    });
  } catch (error) {
    console.error('Daily cleanup failed:', error);
    return NextResponse.json({ ok: false, error: 'Cleanup failed' }, { status: 500 });
  }
}

export const runtime = 'nodejs';
export const maxDuration = 60; // Allow up to 60s for cleanup

2. Inngest Scheduled Functions

typescriptCopy code
// inngest/functions/weekly-report.ts
import { inngest } from '@/lib/inngest';

export const weeklyReportJob = inngest.createFunction(
  {
    id: 'weekly-usage-report',
    name: 'Generate Weekly Usage Report',
  },
  { cron: 'TZ=Asia/Jakarta 0 9 * * 1' }, // Every Monday 9 AM WIB
  async ({ step }) => {
    // Step 1: Gather data
    const metrics = await step.run('gather-metrics', async () => {
      return await db.query.usageMetrics.findMany({
        where: gte(usageMetrics.createdAt, subDays(new Date(), 7)),
      });
    });

    // Step 2: Generate report
    const report = await step.run('generate-report', async () => {
      return generateWeeklyReport(metrics);
    });

    // Step 3: Send to admins
    await step.run('send-report', async () => {
      const admins = await db.query.users.findMany({
        where: eq(users.role, 'admin'),
      });
      for (const admin of admins) {
        await emailQueue.add('weekly-report', { to: admin.email, report });
      }
    });

    return { sent: true, reportId: report.id };
  },
);

3. BullMQ Repeatable Jobs

typescriptCopy code
// queues/scheduled-jobs.ts
import { Queue, Worker } from 'bullmq';

const scheduledQueue = new Queue('scheduled', {
  connection: { host: process.env.REDIS_HOST },
});

// Add repeatable jobs on startup
export async function registerScheduledJobs() {
  // Daily cleanup at 3 AM
  await scheduledQueue.add('daily-cleanup', {}, {
    repeat: { pattern: '0 3 * * *', tz: 'Asia/Jakarta' },
    jobId: 'daily-cleanup', // Prevent duplicates on restart
  });

  // Every 5 minutes: health check
  await scheduledQueue.add('health-check', {}, {
    repeat: { every: 5 * 60 * 1000 }, // 5 minutes in ms
    jobId: 'health-check',
  });

  // Monthly: subscription renewal check (1st of each month at midnight)
  await scheduledQueue.add('subscription-renewal', {}, {
    repeat: { pattern: '0 0 1 * *', tz: 'Asia/Jakarta' },
    jobId: 'subscription-renewal',
  });
}

// Worker
const worker = new Worker('scheduled', async (job) => {
  switch (job.name) {
    case 'daily-cleanup':
      await performDailyCleanup();
      break;
    case 'health-check':
      await performHealthCheck();
      break;
    case 'subscription-renewal':
      await checkSubscriptionRenewals();
      break;
  }
}, { connection: { host: process.env.REDIS_HOST } });

4. Distributed Cron Locking (Redis)

typescriptCopy code
// lib/cron-lock.ts
import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);

/**
 * Acquire a distributed lock to prevent duplicate cron execution
 * across multiple server instances.
 */
export async function acquireCronLock(
  jobName: string,
  ttlSeconds: number = 300,
): Promise<boolean> {
  const lockKey = `cron-lock:${jobName}`;
  // SET NX (only if not exists) with TTL
  const result = await redis.set(lockKey, Date.now().toString(), 'EX', ttlSeconds, 'NX');
  return result === 'OK';
}

export async function releaseCronLock(jobName: string): Promise<void> {
  await redis.del(`cron-lock:${jobName}`);
}

// Usage in cron handler
export async function GET(request: Request) {
  const locked = await acquireCronLock('daily-cleanup', 300);
  if (!locked) {
    return Response.json({ skipped: true, reason: 'Already running on another instance' });
  }

  try {
    await performDailyCleanup();
    return Response.json({ ok: true });
  } finally {
    await releaseCronLock('daily-cleanup');
  }
}

Common Cron Patterns

Common Pitfalls to Avoid

Sovereign Execution, Token Efficiency & Invariants

Bahasa Indonesia

Integrasi Orkestrasi

• Alur Kerja & Pemicu Hulu: async-queue-temporal-expert, event-driven-architect, js-backend-expert
• Platform Cloud & Edge: cloud-hosting-expert, cloudflare-workers-expert
• Tugas Konsumen Domain: saas-billing, email-notification-expert, data-pipeline-etl-expert
• Penguncian & Observabilitas: database-orm-expert, data-telemetry-expert, logging-error-tracking-expert
• Siklus Hidup & Tata Kelola: zero-to-prod-orchestrator, session-memory-manager

Deskripsi

Panduan tingkat produksi untuk mengimplementasikan tugas terjadwal, cron job, dan pekerjaan latar belakang berulang di aplikasi web modern. Mencakup Vercel Cron Jobs, Cloudflare Workers Cron Triggers, Inngest scheduled functions, BullMQ repeatable jobs, distributed cron locking (berbasis Redis), penjadwalan sadar zona waktu, dan kasus penggunaan umum (pembersihan data, pembuatan laporan, health check, perpanjangan langganan).

Kondisi Pemicu

Aktifkan skill ini ketika:

• Menyiapkan tugas terjadwal/berulang (laporan harian, pembersihan, health check).
• Mengonfigurasi Vercel Cron Jobs atau Cloudflare Workers Cron Triggers.
• Mengimplementasikan pemeriksaan perpanjangan langganan atau siklus billing.
• Membangun pipeline agregasi data atau ETL pada jadwal tertentu.
• Membutuhkan penguncian cron terdistribusi untuk mencegah eksekusi duplikat.

Panduan Pemilihan Solusi Cron

Implementasi Pola Kunci (TypeScript)

1. Vercel Cron dengan Proteksi Autentikasi Rahasia (CRON_SECRET)

jsonCopy code
// vercel.json
{
  "crons": [
    {
      "path": "/api/cron/pembersihan-harian",
      "schedule": "0 3 * * *"
    }
  ]
}

typescriptCopy code
// app/api/cron/pembersihan-harian/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  // Verifikasi permintaan resmi berasal dari scheduler Vercel
  const authHeader = request.headers.get('authorization');
  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ error: 'Tidak memiliki otorisasi' }, { status: 401 });
  }

  try {
    // Jalankan operasi pembersihan sesi kadaluarsa
    const hasil = await db.delete(sesiPengguna)
      .where(lt(sesiPengguna.kadaluarsaPada, new Date()));

    return NextResponse.json({ ok: true, terhapus: hasil.rowCount });
  } catch (error) {
    console.error('Pembersihan cron gagal:', error);
    return NextResponse.json({ ok: false, error: 'Gagal membersihkan data' }, { status: 500 });
  }
}

export const runtime = 'nodejs';
export const maxDuration = 60; // Izinkan eksekusi hingga 60 detik

2. Inngest Scheduled Functions Sadar Zona Waktu (TZ=Asia/Jakarta)

typescriptCopy code
import { inngest } from '@/lib/inngest';

export const jobLaporanMingguan = inngest.createFunction(
  { id: 'laporan-mingguan-admin', name: 'Kirim Laporan Penggunaan Mingguan' },
  { cron: 'TZ=Asia/Jakarta 0 9 * * 1' }, // Setiap Senin pukul 09:00 WIB
  async ({ step }) => {
    const dataMetrik = await step.run('ambil-data-metrik', async () => {
      return await kumpulkanMetrik7HariTerakhir();
    });

    const fileLaporan = await step.run('buat-dokumen-laporan', async () => {
      return await generateReportPdf(dataMetrik);
    });

    await step.run('kirimkan-email-admin', async () => {
      await emailQueue.add('kirim-laporan', { file: fileLaporan });
    });

    return { status: 'sukses', terkirim: true };
  }
);

3. Distributed Cron Locking Berbasis Redis (SET NX)

typescriptCopy code
import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);

export async function dapatkanKunciCron(namaTugas: string, durasiDetik: number = 300): Promise<boolean> {
  const kunci = `kunci-cron:${namaTugas}`;
  const status = await redis.set(kunci, Date.now().toString(), 'EX', durasiDetik, 'NX');
  return status === 'OK';
}

export async function lepaskanKunciCron(namaTugas: string): Promise<void> {
  await redis.del(`kunci-cron:${namaTugas}`);
}

Praktik Terbaik Keamanan Cron

• Gunakan Distributed Lock: Mencegah eksekusi ganda ketika aplikasi berjalan pada banyak instans server (cluster/autoscaling).
• Tentukan maxDuration: Hindari cron menggantung tanpa henti yang menghabiskan alokasi sumber daya komputasi.
• Zona Waktu Eksplisit: Selalu sertakan parameter timezone (TZ=Asia/Jakarta) agar jadwal tidak bergeser saat Daylight Saving Time (DST) di cloud server.

Matriks Eksekusi Berdaulat, Efisiensi Token & Invarian