Form Actions: API-Routen für Mutationen ersetzen

In herkömmlichen Next.js-Anwendungen erfordern Formularübermittlungen eine Client Component mit einem onSubmit-Handler, der fetch() aufruft, um Daten per POST an eine API-Route zu senden. Dieses Muster funktioniert, erfordert aber, dass sowohl die clientseitige Fetch-Logik als auch der serverseitige Routen-Handler separat geschrieben und gewartet werden.

Mit Server Actions ersetzen Sie den Fetch-Aufruf und die API-Route durch eine einzige Funktion. Das Formularelement erhält die Server Action als sein action-Prop: <form action={serverAction}>. React fängt die Übermittlung ab und ruft die Action automatisch mit den Formulardaten auf.

Die Server Action erhält automatisch ein FormData-Objekt als Argument, wenn sie durch ein Formular ausgelöst wird. Sie greifen mit formData.get('email') auf einzelne Felder zu; diese Methode gibt den Wert als Zeichenkette zurück. Alle standardmäßigen FormData-Methoden sind verfügbar, einschließlich getAll() für Mehrfachauswahlfelder.

Eine Server Action kann einen serialisierbaren Wert zurückgeben, den der Client verwenden kann. Durch die Rückgabe eines Fehlerobjekts wie { error: 'Email already exists' } oder eines Erfolgskennzeichens wie { success: true } kann der Client die Benutzeroberfläche entsprechend aktualisieren, ohne die gesamte Seite neu zu laden.

Da die Formularaktion eine Server Action ist, muss die Seitenkomponente, die das Formular enthält, keine Client Component sein. Der Server rendert das Formular als statisches HTML, und nur interaktive Teile wie die Fehleranzeige benötigen clientseitiges JavaScript. Dadurch wird das Client-Bundle deutlich kleiner.

Ein Formular mit action={serverAction} funktioniert auch ohne aktiviertes JavaScript. Der Browser führt einen standardmäßigen HTML-Formular-POST aus, der Server führt die Action aus und gibt die aktualisierte Seite zurück. Dieses echte Progressive Enhancement sorgt dafür, dass das Formular in allen Umgebungen zuverlässig funktioniert.

Nachdem eine Server Action Daten verändert hat, müssen zwischengespeicherte Seitendaten aktualisiert werden. Der Aufruf von revalidatePath('/dashboard') innerhalb der Action macht den Next.js-Cache für diesen Pfad ungültig, sodass die nächste Anfrage aktuelle Daten abruft. Dies ist der standardmäßige Weg, serverseitig gerenderte Seiten nach Mutationen aktuell zu halten.

revalidateTag('user-data') ermöglicht eine feiner abgestufte Cache-Invalidierung als revalidatePath. Sie versehen Fetch-Aufrufe mit dem Tag next: { tags: ['user-data'] } und machen anschließend alle mit diesem Tag versehenen Daten innerhalb der Server Action auf einmal ungültig, unabhängig davon, auf welchen Pfaden diese Daten angezeigt werden.

Server Actions können den Benutzer nach einer erfolgreichen Mutation auf eine neue Seite weiterleiten, indem sie redirect('/success') aus dem Modul next/navigation aufrufen. Diese Weiterleitung wird serverseitig verarbeitet, sodass der Browser eine ordnungsgemäße Navigationsantwort statt einer clientseitigen Weiterleitung erhält.

Server Actions sind nicht auf Formularübermittlungen beschränkt. Bei Klicks auf Schaltflächen und anderen Auslösern außerhalb von Formularen verpacken Sie den Aufruf der Action in startTransition(() => action(arg)). Dadurch wird die Navigation als Transition gekennzeichnet, sodass React die aktuelle Benutzeroberfläche sichtbar halten kann, während die Action auf dem Server ausgeführt wird.

Server Actions sind der richtige Ort für serverseitige Validierung. Validieren Sie die FormData-Felder, geben Sie bei Fehlern Validierungsfehler zurück und führen Sie die Mutation nur aus, wenn alle Felder gültig sind. Bibliotheken wie Zod lassen sich hier gut integrieren: Parsen Sie die FormData anhand eines typisierten Schemas und geben Sie bei einem Fehler die Fehlerzuordnung zurück.

Welches Argument erhält eine Server Action, wenn sie durch eine Formularübermittlung ausgelöst wird?

Server Actions ersetzen das Muster aus Fetch und API-Route für Mutationen von Formularen. Das action-Prop des Formulars akzeptiert direkt eine Server Action, die ein FormData-Objekt erhält. Actions geben serialisierbare Ergebnisse für Aktualisierungen der Client-Oberfläche zurück, unterstützen revalidatePath und revalidateTag zur Cache-Invalidierung und funktionieren dank Progressive Enhancement auch ohne JavaScript.