Jak uruchamiać zadania cron (Scheduled Tasks) w Next.js?

Problem: Next.js nie ma wbudowanego crona

Z tej luki wychodzi się na trzy sposoby, każdy do innej skali problemu: Vercel Cron Jobs, Upstash QStash i GitHub Actions cron. Po kolei.

Vercel Cron Jobs w Next.js

Vercel pozwala definiować cron jobs w vercel.json. Takie zadania wywołują Route Handlery o określonych porach.

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "crons": [
    {
      "path": "/api/cron/daily-report",
      "schedule": "0 8 * * *"
    },
    {
      "path": "/api/cron/cleanup",
      "schedule": "0 3 * * 0"
    },
    {
      "path": "/api/cron/check-subscriptions",
      "schedule": "0 */6 * * *"
    }
  ]
}

Składnia cron: minute hour day-of-month month day-of-week

• 0 8 * * *: codziennie o 8:00 UTC
• 0 3 * * 0: co niedzielę o 3:00 UTC
• 0 */6 * * *: co 6 godzin
• */15 * * * *: co 15 minut

Vercel interpretuje harmonogram w UTC i wywołuje metodą GET wyłącznie aktualne wdrożenie produkcyjne. Nie używaj lokalnej godziny bez przeliczenia zmian czasu letniego. Cron nie podąża też za odpowiedziami 3xx, więc path musi prowadzić bezpośrednio do istniejącego handlera, bez przekierowania.

Route Handler jako adres zadania cron

// app/api/cron/daily-report/route.ts
import { NextResponse } from 'next/server'
import { resend } from '@/lib/resend'
import { db } from '@/lib/db'
 
export const maxDuration = 60
 
export async function GET(request: Request) {
  // Weryfikacja: tylko Vercel Cron może wywołać ten adres.
  const authHeader = request.headers.get('authorization')
  const cronSecret = process.env.CRON_SECRET
 
  if (!cronSecret || authHeader !== `Bearer ${cronSecret}`) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }
 
  const end = new Date()
  end.setUTCHours(0, 0, 0, 0)
  const start = new Date(end)
  start.setUTCDate(start.getUTCDate() - 1)
  const reportDate = start.toISOString().slice(0, 10)
 
  const stats = await db.order.aggregate({
    _count: true,
    _sum: { total: true },
    where: {
      createdAt: { gte: start, lt: end },
    },
  })
 
  const { error } = await resend.emails.send(
    {
      from: 'NazwaFirmy <raporty@example.com>',
      to: 'mike@example.com',
      subject: `Raport dzienny: ${reportDate}`,
      html: `
        <h2>Raport za ${reportDate}</h2>
        <p>Zamówienia: ${stats._count}</p>
        <p>Przychód: ${stats._sum.total || 0} PLN</p>
      `,
    },
    // Chroni wysyłkę przed podwójnym wywołaniem tego samego dnia.
    { idempotencyKey: `daily-report/${reportDate}` },
  )
 
  if (error) throw new Error(`Nie udało się wysłać raportu: ${error.message}`)
 
  return NextResponse.json({
    success: true,
    orders: stats._count,
    revenue: stats._sum.total,
  })
}

Zabezpieczenie zadania cron przez CRON_SECRET

# .env.local / Vercel Environment Variables
CRON_SECRET=twoj-tajny-klucz-minimum-32-znaki

W panelu Vercel przejdź do zakładki Settings, a następnie Environment Variables i dodaj zmienną CRON_SECRET. Vercel będzie automatycznie przekazywał jej wartość w nagłówku Authorization przy każdym wywołaniu zadania cron.

maxDuration jest wskazówką dla platformy wdrożeniowej, a nie sposobem na nieograniczone wykonanie. Rzeczywisty limit zależy od hostingu i planu. Vercel nie ponawia nieudanych zadań cron, może jednak uruchomić ten sam termin więcej niż raz i rozpocząć kolejne wykonanie, zanim poprzednie zdąży się zakończyć. Klucz idempotencji u dostawcy poczty elektronicznej zabezpiecza wyłącznie tę pojedynczą operację, dlatego zmiany w bazie danych należy chronić transakcjami oraz unikalnymi kluczami biznesowymi. Dodatkowo, przed równoległym uruchomieniem zadań warto zastosować blokadę rozproszoną z czasem wygaśnięcia TTL.

Upstash QStash jako bezserwerowa kolejka wiadomości

QStash to kolejka wiadomości z HTTP API. Sprawdza się przy zadaniach, które mają być dostarczone co najmniej raz ( at-least-once delivery), mogą być opóźnione albo wymagają automatycznego ponawiania. „Co najmniej raz” oznacza, że odbiorca musi tolerować duplikaty.

npm install @upstash/qstash

QSTASH_TOKEN=...
QSTASH_CURRENT_SIGNING_KEY=...
QSTASH_NEXT_SIGNING_KEY=...
APP_URL=https://example.com

Zaplanowanie zadania w Upstash QStash

// actions/schedule-report.ts
'use server'
 
import { Client } from '@upstash/qstash'
import { requireAdmin } from '@/lib/auth'
 
const qstashToken = process.env.QSTASH_TOKEN
const appUrl = process.env.APP_URL
 
if (!qstashToken || !appUrl) {
  throw new Error('Brakuje QSTASH_TOKEN lub APP_URL')
}
 
const qstash = new Client({
  token: qstashToken,
})
 
export async function scheduleWeeklyReport() {
  await requireAdmin()
 
  const jobId = crypto.randomUUID()
  const result = await qstash.publishJSON({
    url: `${appUrl}/api/cron/weekly-report`,
    body: { jobId, type: 'weekly' },
    retries: 3, // 3 ponowienia po pierwszym wywołaniu
    failureCallback: `${appUrl}/api/qstash/failure`,
  })
 
  return { jobId, messageId: result.messageId }
}
 
// Zaplanowanie z opóźnieniem
export async function scheduleReminder(userId: string, delayMinutes: number) {
  await requireAdmin()
 
  if (!userId || !Number.isInteger(delayMinutes) || delayMinutes < 1) {
    throw new Error('Nieprawidłowy użytkownik lub opóźnienie')
  }
 
  await qstash.publishJSON({
    url: `${appUrl}/api/reminders`,
    body: { userId, type: 'trial-ending' },
    delay: `${delayMinutes}m`,
  })
}

Zmienne QSTASH_TOKEN oraz APP_URL są wykorzystywane wyłącznie po stronie serwera, dlatego nie wymagają publicznego prefiksu. Warto też pamiętać, że Server Action nie stanowi pełnej granicy zaufania, ponieważ przed uruchomieniem kosztownego zadania należy każdorazowo zweryfikować sesję użytkownika, jego rolę oraz poprawność danych wejściowych. Ponadto parametr retries: 3 oznacza dokładnie trzy dodatkowe ponowienia po pierwszej próbie, co daje łącznie maksymalnie cztery próby dostarczenia zadania.

Odbiór zadania QStash w Route Handler

// app/api/cron/weekly-report/route.ts
import { verifySignatureAppRouter } from '@upstash/qstash/nextjs'
 
type WeeklyReportJob = { jobId: string; type: 'weekly' }
 
function isWeeklyReportJob(value: unknown): value is WeeklyReportJob {
  return (
    typeof value === 'object' &&
    value !== null &&
    'jobId' in value &&
    typeof value.jobId === 'string' &&
    'type' in value &&
    value.type === 'weekly'
  )
}
 
async function handler(request: Request) {
  const body: unknown = await request.json()
 
  if (!isWeeklyReportJob(body)) {
    // Błąd trwały: nie zużywaj ponowień na wadliwy payload.
    return new Response('Invalid payload', {
      status: 489,
      headers: { 'Upstash-NonRetryable-Error': 'true' },
    })
  }
 
  const report = await generateWeeklyReport()
  await sendReportEmail(report, {
    idempotencyKey: `weekly-report/${body.jobId}`,
  })
 
  return new Response('OK')
}
 
// QStash automatycznie weryfikuje podpis. Żadne inne żądanie nie przejdzie.
export const POST = verifySignatureAppRouter(handler)

Wrapper wymaga trzech sekretów z konsoli Upstash: QSTASH_TOKEN do publikowania oraz QSTASH_CURRENT_SIGNING_KEY i QSTASH_NEXT_SIGNING_KEY do weryfikacji rotowanych podpisów. Weryfikacja podpisu potwierdza nadawcę, ale nie zapobiega ponownemu dostarczeniu poprawnie podpisanej wiadomości. jobId musi więc trafić do trwałego klucza idempotencji, unikalnego indeksu albo transakcji. Funkcja sendReportEmail z przykładu powinna przekazać ten klucz do dostawcy wiadomości.

Typowe zastosowania QStash w Next.js

// 1. Wyślij email powitalny 30 minut po rejestracji
await qstash.publishJSON({
  url: 'https://api.example.com/emails/welcome',
  body: { userId: newUser.id },
  delay: '30m',
})
 
// 2. Sprawdź status płatności za 24h
await qstash.publishJSON({
  url: 'https://api.example.com/cron/check-payment',
  body: { orderId: order.id },
  delay: '1d',
})
 
// 3. Cykliczne czyszczenie przez QStash schedules
await qstash.schedules.create({
  destination: `${appUrl}/api/cron/cleanup`,
  scheduleId: 'daily-cleanup',
  cron: 'CRON_TZ=Europe/Warsaw 0 3 * * *',
  failureCallback: `${appUrl}/api/qstash/failure`,
})

QStash schedules mają maksymalną rozdzielczość jednej minuty; dostarczenie pojedynczej wiadomości możesz natomiast opóźnić o sekundy. Jawny scheduleId pozwala aktualizować istniejący harmonogram zamiast przypadkowo tworzyć kolejny przy każdym wdrożeniu. Po wyczerpaniu ponowień obsłuż failureCallback albo kontroluj kolejkę niedostarczonych zadań (Dead Letter Queue). Adres failureCallback jest również publiczny, dlatego zabezpiecz go przez verifySignatureAppRouter, tak jak adres odbierający zadanie.

GitHub Actions cron jako alternatywa

Dla prostych zadań GitHub Actions może uruchamiać workflow według harmonogramu:

# .github/workflows/daily-report.yml
name: Daily Report
 
on:
  schedule:
    - cron: '0 8 * * *'
      timezone: 'Europe/Warsaw'
 
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger report endpoint
        run: |
          curl --fail-with-body --silent --show-error \
            -H "Authorization: Bearer ${{ secrets.CRON_SECRET }}" \
            https://example.com/api/cron/daily-report

Najkrótszy obsługiwany interwał wynosi 5 minut, ale GitHub nie daje nam jakichkolwiek gwarancji punktualnego startu. Przy dużym obciążeniu workflow może się opóźnić, a oczekujące uruchomienie nawet wypaść (szczególnie obciążony bywa początek godziny). Harmonogram działa tylko z domyślnej gałęzi, a w publicznym repozytorium zostaje automatycznie wyłączony po 60 dniach bez aktywności. Koszt zależy od widoczności repozytorium, użytego runnera i planu GitHub, więc nie zakładaj stałego limitu 2000 darmowych minut.

Czy cron powinien działać na Edge Runtime?

Edge Runtime nie jest harmonogramem, ale środowiskiem wykonania, więc nadal potrzebujesz Vercel Cron, QStash, GitHub Actions albo systemowego crona, który wywoła adres zadania. W Next.js domyślnym i rekomendowanym środowiskiem wykonania Route Handlera jest Node.js. Wybór export const runtime = 'edge' ma sens tylko wtedy, gdy wszystkie zależności zadania, w tym klient bazy i SDK dostawców, obsługują Edge. Nie omija też limitów czasu platformy.

after() z Next.js również nie zastępuje crona. Pozwala kontynuować pracę po wysłaniu odpowiedzi, ale callback nadal działa w ramach maxDuration tego samego wywołania i sam nie uruchomi się o wybranej godzinie. Podobnie setInterval lub timer utworzony przy starcie modułu jest niewiarygodny w środowisku bezserwerowym: instancja może zostać zamrożona albo usunięta w dowolnym momencie.

Idempotencja, blokady i monitoring zadań cron

Nie projektuj zadania na założeniu dokładnie jednego wykonania. Vercel może zarówno pominąć, jak i powtórzyć termin. QStash wykonuje skonfigurowaną liczbę ponowień, więc ta sama wiadomość może dotrzeć więcej niż raz. GitHub Actions może wystartować później lub pominąć oczekujące wykonanie przy dużym obciążeniu.

Idempotencję buduj na stabilnym kluczu biznesowym, np. daily-report/2026-07-16 albo ID konkretnego zdarzenia. Zapisuj go w bazie z unikalnym indeksem i używaj transakcji tam, gdzie skutek dotyczy danych. Dla zewnętrznych efektów ubocznych korzystaj z kluczy idempotencji dostawcy. Deduplication QStash ogranicza ponowne opublikowanie wiadomości w dziesięciominutowym oknie, ale nie zwalnia odbiorcy z obsługi powtórnego dostarczenia.

Jeżeli dwa wykonania nie mogą działać równolegle, zastosuj blokadę we współdzielonym magazynie z właścicielem i TTL dłuższym od typowego czasu zadania. Zwolnienie blokady umieść w finally, ale nie polegaj wyłącznie na ręcznym zwolnieniu, bo proces może zostać przerwany. Dla dużej liczby elementów zapisuj punkt kontrolny i przetwarzaj małe porcje, aby następne wykonanie mogło bezpiecznie wznowić pracę.

Monitoruj początek, koniec, czas trwania, liczbę przetworzonych rekordów, identyfikator uruchomienia i wynik. Zwracaj 2xx dopiero po rzeczywistym sukcesie; błąd przejściowy powinien dać 5xx, aby QStash wykonał ponowienie. Oprócz logów ustaw zewnętrzny sygnał kontrolny z maksymalnym dopuszczalnym opóźnieniem oraz alert na brak wykonania, bo brak żądania nie wygeneruje wyjątku w aplikacji.

Vercel Cron vs Upstash QStash vs GitHub Actions