Next.js-Entwickler in Mannheim

Mein Name ist Mariusz Szatkowski. Ich entwickle allein, von Gdynia aus, und arbeite seit 2006 mit WordPress. Für Mannheim schreibe ich über Arbeit, die in einer Next.js-Anwendung nicht in die Anfrage gehört: Mails in großer Zahl, Importe, PDF-Erzeugung, den Abgleich mit dem ERP. Meine Angaben zu Next.js stammen aus der Dokumentation auf nextjs.org. Laut npm-Registry ist 16.4.6 vom 9. November 2026 die neueste Version.

Nach Angabe der Stadt sind Neckar und Rhein mit Europas viertgrößtem Binnenhafen verbunden, und der Einzelhandel nimmt eine herausragende Position ein (Wirtschaftsstandort Mannheim). Wer Waren umschlägt oder verkauft, hat fast immer ein Warenwirtschaftssystem im Hintergrund, und die Webanwendung davor muss mit dessen Takt leben. Genau dort entstehen die Probleme, um die es hier geht.

Foto: Maarten Sepp, CC BY-SA 3.0, Wikimedia Commons.

#Was nicht in eine Anfrage gehört

Eine Anfrage hat einen Nutzer, der wartet, und eine Plattform, die irgendwann abbricht. Arbeit, die länger dauert oder fehlschlagen darf, ohne dass der Nutzer es merken soll, gehört woanders hin:

Wie Sie mit langsamen Fremdsystemen beim Rendern umgehen, beschreibt die Seite zu Datenabruf und Streaming in Karlsruhe. Hier geht es um die Arbeit, die gar nicht mehr auf die Antwort warten soll.

#after(): kurze Arbeit nach der Antwort

Laut Dokumentation plant after Arbeit ein, die nach dem Ende der Antwort oder des Prerenderings läuft. Genannte Beispiele sind Protokollierung und Analytics. Aufrufen lässt sich die Funktion in Server Components, Server Functions, Route Handlers und im Proxy. Seit Next.js 15.1.0 ist sie stabil.

// app/api/anfrage/route.ts
import { after } from 'next/server'

export async function POST(request: Request) {
  const daten = await request.json()
  const id = await speichereAnfrage(daten) // schnell, in der Anfrage

  after(async () => {
    await sendeBestaetigung(id) // läuft nach der Antwort
  })

  return Response.json({ id }, { status: 202 })
}

Vier Eigenschaften aus der Dokumentation sind für die Planung wichtig:

• Der Callback läuft auch, wenn die Antwort nicht erfolgreich war, etwa bei einem Fehler, bei notFound() oder redirect().
• Er läuft höchstens so lange, wie die Plattform oder die Route-Konfiguration maxDuration erlaubt.
• In Route Handlers und Server Functions dürfen cookies() und headers() im Callback stehen. In Server Components nicht: Dort werfen sie einen Laufzeitfehler, die Werte müssen vorher gelesen und hineingereicht werden.
• Auf einer statischen Seite läuft der Callback beim Build oder bei der Neuvalidierung, after macht die Route nicht dynamisch.

Was die Dokumentation nicht verspricht: eine Wiederholung. Stirbt der Prozess mitten im Callback, ist die Arbeit weg. after passt deshalb zu Aufgaben, deren Verlust verschmerzbar ist, oder als Anstoß, der einen dauerhaften Eintrag erzeugt. Die Plattform-Tabelle der Dokumentation führt Node.js-Server und Docker mit Ja, den statischen Export mit Nein und Adapter plattformabhängig. Webhooks, die schnell antworten und danach arbeiten, behandelt die Seite zu Route Handlers in Wuppertal.

#Cron und Warteschlange: was der Host liefert

Vercel nennt in seiner Übersicht zu Hintergrundarbeit mehrere Bausteine: after() für kurze Aufgaben nach einer Antwort, Queues für ereignisgesteuerte Jobs mit Wiederholung, Cron Jobs für wiederkehrende Starts und Workflows für Abläufe mit mehreren Schritten. Ein Cron Job kann demnach eine Aufgabe erledigen, Arbeit in eine Queue stellen oder einen Workflow starten.

Für den Cron-Teil gelten laut Vercel-Dokumentation diese Regeln:

• Vercel ruft per HTTP GET den Pfad aus der vercel.json auf, und zwar am Produktions-Deployment. Auf Preview-Deployments laufen Cron Jobs nicht.
• Die Zeitzone ist immer UTC. Ein Lauf “um 2 Uhr nachts” ist im Sommer 4 Uhr in Mannheim.
• Ein fehlgeschlagener Aufruf wird nicht wiederholt.
• Die Zustellung ist bestmöglich: Ein Lauf kann ausfallen, und derselbe Lauf kann gelegentlich doppelt ankommen.
• Läuft ein Job länger als das Intervall, kann ein zweiter Lauf parallel starten. Vercel empfiehlt eine Sperre, etwa eine verteilte Sperre in Redis.
• Mit der Umgebungsvariable CRON_SECRET sendet Vercel einen Authorization-Header, den der Handler prüfen sollte.

Die Seite selbst markiert Cron Jobs als Altbestand, der künftig in “Schedules” übergeht. Ich prüfe vor einem Projekt den dann aktuellen Stand der Dokumentation, statt mich auf diese Seite zu verlassen. Wo die Anwendung nicht bei Vercel läuft, liefert der Betrieb Cron selbst: ein Systemdienst oder ein geplanter Container-Start, der einen geschützten Endpunkt aufruft oder direkt den Worker anstößt. Die Betriebswege vergleicht die Seite zu Selbsthosting in Berlin.

#Ein eigener Worker mit Postgres-Warteschlange

Wenn die Arbeit gelingen muss, brauche ich einen dauerhaften Ort für den Auftrag. Als Beispiel nehme ich pg-boss, eine Job-Warteschlange für Node.js auf PostgreSQL. Die Version 12.38.2 erschien laut npm-Registry am 10. November 2026 und verlangt Node 22.12 oder höher sowie PostgreSQL 13 oder höher. Das passt gut, wenn die Anwendung ohnehin eine Datenbank hat; zu Postgres als Datenbank siehe Dresden. Wer schon Redis betreibt, kann BullMQ nehmen, das Prinzip bleibt gleich.

Die Anwendung stellt nur Aufträge ein. Ein zweiter Prozess, der Worker, arbeitet sie ab:

// worker.ts: eigener Prozess, nicht Teil des Next.js-Servers
import { PgBoss } from 'pg-boss'

const boss = new PgBoss(process.env.DATABASE_URL!)
boss.on('error', (fehler) => console.error('pg-boss', fehler))
await boss.start()

await boss.createQueue('rechnung-pdf-fehler')
await boss.createQueue('rechnung-pdf', {
  retryLimit: 5,
  retryDelay: 60,
  retryBackoff: true,
  deadLetter: 'rechnung-pdf-fehler',
})

await boss.work('rechnung-pdf', async ([job]) => {
  await erzeugeUndVersendePdf(job.data.rechnungId)
})

Und in der Anwendung: await boss.send('rechnung-pdf', { rechnungId }). Die Optionen stehen in der pg-boss-Dokumentation: retryLimit mit Standardwert 2, retryDelay in Sekunden, retryBackoff für wachsende Abstände, deadLetter für eine Zielwarteschlange nach der letzten Wiederholung. Standardmäßig darf ein Job 15 Minuten aktiv sein (expireInSeconds), danach wird er wiederholt oder gilt als fehlgeschlagen. Für Zeitpläne gibt es schedule() mit Cron-Ausdruck und Zeitzone, Zeitpläne laufen nur, solange mindestens eine Instanz läuft.

Auch hier gilt: Der Worker ist ein zusätzlicher Prozess, den jemand betreibt, überwacht und bei Deployments neu startet. Das ist der eigentliche Preis dieser Lösung, und ich nenne ihn vor dem Bau.

#Idempotenz und Wiederholungen

Die pg-boss-Dokumentation sagt es ohne Umschweife: Jobs werden mindestens einmal ausgeliefert. Stürzt ein Worker ab oder läuft ein Job über seine Frist, wird er wiederholt, ein Handler kann für denselben Job mehrfach laufen. Vercel beschreibt für Cron dasselbe Muster mit doppelten und verpassten Läufen. Daraus folgt eine Regel für jeden Handler: Zweimal ausgeführt darf er nichts doppelt tun.

• Zustand prüfen, dann handeln. “Rechnung versendet am” in der Datenbank setzen und vor dem Versand lesen. Vercel nennt als Gegenbeispiel “Guthaben um 10 erhöhen”, das bei Doppelausführung doppelt zählt.
• Eindeutige Kennung für externe Aktionen. Das ERP oder der Zahlungsdienst bekommt die Auftragsnummer als Schlüssel, damit ein wiederholter Aufruf keine zweite Buchung erzeugt. Ob die fremde Schnittstelle das unterstützt, steht in deren Dokumentation und gehört in die Klärung vor Projektbeginn.
• Doppelte Einträge vermeiden. pg-boss kennt dafür Warteschlangen-Richtlinien wie short (nur ein wartender Job) und singletonKey, mit denen ein zweiter gleicher Auftrag gar nicht erst entsteht. Das ersetzt die Prüfung im Handler nicht, es spart nur Arbeit.
• Aufholen statt zählen. Ein nächtlicher Abgleich fragt “was ist seit dem letzten erfolgreichen Lauf neu” und nicht “was war gestern”. So heilt ein verpasster Lauf von selbst.
• Wiederholung mit wachsendem Abstand. Ein ERP, das gerade nicht antwortet, bekommt nicht im Sekundentakt Anfragen. retryBackoff leistet das.

#Fehlgeschlagene Jobs sichtbar machen

Ein stiller Fehler ist schlimmer als ein lauter. Drei Dinge müssen stimmen:

1. Dead-Letter-Queue. Nach der letzten Wiederholung wird laut Dokumentation der Auftrag in die dort genannte Warteschlange kopiert. Dort sammelt sich, was Menschen ansehen müssen.
2. Alarm auf die Warteschlange, nicht auf jeden Versuch. Ein einzelner Fehlversuch mit späterem Erfolg ist keine Störung. Ein Eintrag in der Dead-Letter-Queue ist eine. Zu Alarmen, die nicht ermüden, siehe die Seite zu Fehlerbehandlung in Essen.
3. Error-Listener am Worker. pg-boss warnt in seiner Dokumentation, dass ein fehlender error-Listener den Prozess beenden kann. Das Beispiel oben setzt ihn deshalb.

Zur Beobachtung bietet pg-boss ein Dashboard als eigenes Paket und OpenTelemetry-Spuren und -Metriken. Für den Next.js-Teil gibt instrumentation.ts die Stelle vor, an der Serverfehler zusammenlaufen.

Ein Datenschutzaspekt: Was im Auftrag steht, liegt in einer Tabelle. Ich lege in den Auftrag eine Kennung und keine Klartextdaten, damit die Dead-Letter-Queue keine zweite Kundendatenbank wird. Geht ein Versand schief und eine Rechnung an die falsche Adresse, stellt sich die Frage nach Art. 33 DSGVO. Der LfDI Baden-Württemberg schreibt dazu, nicht jede Verletzung führe zu einer Meldepflicht; entscheidend sei die Annahme eines Risikos für die Rechte und Freiheiten. Die Bewertung liegt bei Ihrer Datenschutzberatung. Mein Teil ist ein Protokoll, aus dem sich ablesen lässt, wer was wann bekommen hat.

#Selbst betrieben: sauber herunterfahren

Laut Selbsthosting-Anleitung ist after mit next start voll unterstützt. Beim Stoppen sendet man SIGINT oder SIGTERM und wartet: Der Server beendet laufende Anfragen und führt offene after-Callbacks aus, bevor er sich beendet. Empfohlen wird eine konfigurierbare Auslaufzeit von 10 bis 30 Sekunden. Wer Container ohne diese Frist hart beendet, verliert Callbacks. Bei einem eigenen Worker gilt dasselbe: Er braucht ein Signal-Verhalten, das laufende Jobs zu Ende bringt oder freigibt, und die Warteschlange fängt den Rest auf.

#Checkliste für Ihre Hintergrundarbeit

#So läuft ein Projekt mit mir

Ich arbeite aus der Ferne und schriftlich, ohne Termine und Telefonate. Als Start reichen eine Mail mit Adresse, Ziel und Frist. Danach lese ich den Code, stelle meine Fragen schriftlich und liste, welche Aufgaben heute in Anfragen laufen. Schriftlich erhalten Sie den Umfang samt Annahmen. Gebaut wird auf einer Staging-Umgebung, live geht erst, was Sie schriftlich freigegeben haben. Gestaltung, Mockups und Wireframes liefern Sie; ich setze sie um.

Läuft die Anwendung später weiter, beschreibt die Seite zur Wartung in Mannheim die Betreuung mit getesteten Updates und monatlichem Bericht. Besteht Ihre Anwendung hauptsächlich aus Inhalten, prüfe ich vorab, ob Astro in Mannheim weniger Betrieb bedeutet.

#Häufige Fragen

Läuft after() auch, wenn die Antwort an den Nutzer schon gesendet ist? Ja, dafür ist es gedacht. Laut Dokumentation plant after() Arbeit nach dem Ende der Antwort ein und führt sie auch aus, wenn die Antwort nicht erfolgreich war, etwa bei einem Fehler, notFound() oder redirect(). Die Arbeit läuft höchstens so lange, wie die Plattform für die Route erlaubt.

Ist after() eine Warteschlange? Nein. Die Funktion hat keine Wiederholung, keine Ablage und kein Protokoll. Stirbt der Prozess mitten im Callback, ist die Arbeit weg. Für Aufgaben, die gelingen müssen, gehört ein Eintrag in eine Warteschlange oder eine Tabelle dazu.

Reicht ein Cron-Aufruf von Vercel für einen nächtlichen ERP-Abgleich? Nur mit Vorsicht. Laut Vercel wiederholt die Plattform einen fehlgeschlagenen Aufruf nicht, die Zustellung ist bestmöglich, und derselbe Lauf kann gelegentlich doppelt ankommen. Der Abgleich muss deshalb verpasste und doppelte Läufe vertragen: alles seit dem letzten erfolgreichen Lauf nachholen, bereits Erledigtes erkennen.

Brauche ich für einen Worker einen eigenen Server? Ein eigener Prozess ja, ein eigener Server nicht zwingend. Der Worker kann als zweiter Container neben der Anwendung laufen. Bei pg-boss genügt eine PostgreSQL-Datenbank, die Sie oft schon haben. Ob das für Ihre Last und Ihren Betrieb passt, kläre ich vorab schriftlich.

Muss ich einen fehlgeschlagenen Versand von Rechnungen melden? Nicht jeder Fehler ist eine Datenpanne. Der LfDI Baden-Württemberg schreibt auf seiner Seite, nicht jede Verletzung führe zu einer Meldepflicht nach Art. 33 DSGVO; entscheidend sei die Annahme eines Risikos für die Rechte und Freiheiten. Geht eine Rechnung an den falschen Empfänger, prüft das Ihre Datenschutzberatung. Ich sorge dafür, dass sich der Fall im Protokoll nachvollziehen lässt.

Gestalten Sie auch das Layout? Nein, das Layout bringen Sie mit. Aus Ihrer Vorlage baue ich die responsive Oberfläche; welches Element wohin kommt, tragen Sie in eine Tabelle ein.

#Ihre Hintergrundjobs in einer E-Mail

Läuft in Ihrer Anwendung etwas zu lange für eine Anfrage, oder geht ein Auftrag ab und zu verloren, ohne dass es jemand bemerkt? Eine Nachricht an mich geht über das Kontaktformular ein. Nennen Sie die Adresse der Anwendung, die betroffene Aufgabe, das Fremdsystem dahinter, Ihr Ziel und den Wunschtermin. Kostenlos ist die erste schriftliche Schätzung. Auf Rückfragen antworte ich an Werktagen schriftlich.