Form Actions: zastępowanie tras API dla mutacji

W tradycyjnych aplikacjach Next.js przesyłanie formularzy wymaga komponentu klienckiego z procedurą obsługi onSubmit, która wywołuje fetch(), aby wysłać dane metodą POST do trasy API. Ten wzorzec działa, ale wymaga osobnego napisania i utrzymywania zarówno logiki fetch po stronie klienta, jak i procedury obsługi trasy po stronie serwera.

W przypadku Server Actions wywołanie fetch i trasę API zastępuje jedna funkcja. Element formularza otrzymuje Server Action jako swój prop action: <form action={serverAction}>. React przechwytuje przesłanie formularza i automatycznie wywołuje akcję z danymi formularza.

Server Action automatycznie otrzymuje obiekt FormData jako argument, gdy zostanie uruchomiona przez formularz. Poszczególne pola można odczytywać za pomocą formData.get('email'), które zwraca wartość jako ciąg znaków. Dostępne są wszystkie standardowe metody FormData, w tym getAll() do obsługi pól wielokrotnego wyboru.

Server Action może zwrócić wartość, którą można serializować i którą klient może wykorzystać. Zwrócenie obiektu błędu, takiego jak { error: 'Email already exists' }, albo flagi powodzenia, takiej jak { success: true }, pozwala klientowi odpowiednio zaktualizować interfejs bez pełnego przeładowania strony.

Ponieważ akcją formularza jest Server Action, komponent strony zawierający formularz nie musi być Client Component. Serwer renderuje formularz jako statyczny kod HTML, a tylko elementy interaktywne, takie jak wyświetlanie błędów, wymagają JavaScriptu po stronie klienta. Znacznie zmniejsza to rozmiar bundla klienckiego.

Formularz z action={serverAction} działa bez włączonego JavaScriptu. Przeglądarka wykonuje standardowe przesłanie formularza HTML metodą POST, serwer wykonuje akcję, a następnie zwraca zaktualizowaną stronę. To prawdziwe progresywne ulepszanie sprawia, że formularz działa poprawnie w każdym środowisku, nawet przy ograniczonej funkcjonalności.

Po tym, jak Server Action zmodyfikuje dane, dane stron przechowywane w pamięci podręcznej muszą zostać odświeżone. Wywołanie revalidatePath('/dashboard') wewnątrz akcji unieważnia pamięć podręczną Next.js dla tej ścieżki, dzięki czemu następne żądanie pobierze aktualne dane. Jest to standardowy sposób na utrzymywanie aktualności stron renderowanych po stronie serwera po wykonaniu mutacji.

revalidateTag('user-data') zapewnia bardziej precyzyjne unieważnianie pamięci podręcznej niż revalidatePath. Wywołania fetch oznacza się tagami za pomocą next: { tags: ['user-data'] }, a następnie z poziomu Server Action unieważnia się jednocześnie wszystkie dane opatrzone tym tagiem, niezależnie od tego, na jakich ścieżkach są wyświetlane.

Server Actions mogą przekierować użytkownika na nową stronę po pomyślnej mutacji przez wywołanie redirect('/success') z modułu next/navigation. To przekierowanie jest obsługiwane po stronie serwera, dzięki czemu przeglądarka otrzymuje prawidłową odpowiedź nawigacji zamiast przekierowania po stronie klienta.

Server Actions nie ograniczają się do przesyłania formularzy. W przypadku kliknięć przycisków i innych wyzwalaczy niezwiązanych z formularzem należy opakować wywołanie akcji w startTransition(() => action(arg)). Oznacza to nawigację jako przejście, dzięki czemu React może pozostawić bieżący interfejs widoczny podczas wykonywania akcji na serwerze.

Server Actions są właściwym miejscem do przeprowadzania walidacji po stronie serwera. Należy zwalidować pola FormData, zwrócić błędy walidacji w razie niepowodzenia i wykonać mutację dopiero wtedy, gdy wszystkie pola są poprawne. Biblioteki takie jak Zod dobrze się tu sprawdzają: można przeanalizować FormData zgodnie ze schematem typów i w razie niepowodzenia zwrócić mapę błędów.

Server Actions zastępują wzorzec fetch + trasa API w przypadku mutacji wykonywanych przez formularze. Prop formularza action przyjmuje bezpośrednio Server Action, która otrzymuje obiekt FormData. Akcje zwracają wyniki możliwe do serializowania, aby umożliwić aktualizowanie interfejsu klienta, obsługują revalidatePath i revalidateTag do unieważniania pamięci podręcznej oraz działają progresywnie bez JavaScriptu.