Acciones de formularios: sustitución de las rutas de API para mutaciones

En las aplicaciones tradicionales de Next.js, los envíos de formularios requieren un componente de cliente con un controlador onSubmit que llame a fetch() para enviar los datos mediante POST a una ruta de API. Este patrón funciona, pero exige escribir y mantener por separado tanto la lógica de fetch del lado del cliente como el controlador de la ruta del lado del servidor.

Con Server Actions, se sustituyen la llamada a fetch y la ruta de API por una sola función. El elemento de formulario recibe el Server Action como su propiedad action: <form action={serverAction}>. React intercepta el envío y llama automáticamente a la acción con los datos del formulario.

El Server Action recibe automáticamente un objeto FormData como argumento cuando se activa desde un formulario. Puede acceder a cada campo mediante formData.get('email'), que devuelve el valor como una cadena. Todos los métodos estándar de FormData están disponibles, incluido getAll() para campos de selección múltiple.

Un Server Action puede devolver un valor serializable que el cliente puede utilizar. Devolver un objeto de error como { error: 'Email already exists' } o un indicador de éxito como { success: true } permite al cliente actualizar la interfaz de usuario según corresponda sin recargar toda la página.

Como la acción del formulario es un Server Action, el componente de página que contiene el formulario no necesita ser un componente de cliente. El servidor renderiza el formulario como HTML estático y solo las partes interactivas, como la visualización de errores, requieren JavaScript del lado del cliente. Esto reduce considerablemente el bundle del cliente.

Un formulario con action={serverAction} funciona sin JavaScript habilitado. El navegador realiza un POST de formulario HTML estándar, el servidor ejecuta la acción y devuelve la página actualizada. Esta verdadera mejora progresiva permite que el formulario funcione correctamente en cualquier entorno.

Después de que un Server Action modifique los datos, es necesario actualizar los datos almacenados en caché de la página. La llamada a revalidatePath('/dashboard') dentro de la acción invalida la caché de Next.js para esa ruta, lo que hace que la siguiente solicitud obtenga datos actualizados. Esta es la forma estándar de mantener actualizadas las páginas renderizadas en el servidor después de las mutaciones.

revalidateTag('user-data') proporciona una invalidación de caché más específica que revalidatePath. Puede etiquetar las llamadas a fetch con next: { tags: ['user-data'] } y después invalidar de una sola vez todos los datos etiquetados desde el Server Action, independientemente de las rutas que los muestren.

Los Server Actions pueden redirigir al usuario a una página nueva después de una mutación correcta mediante una llamada a redirect('/success') desde el módulo next/navigation. Esta redirección se gestiona en el servidor, por lo que el navegador recibe una respuesta de navegación adecuada en lugar de una redirección del lado del cliente.

Los Server Actions no se limitan a los envíos de formularios. Para clics en botones y otros activadores que no sean formularios, envuelva la llamada a la acción en startTransition(() => action(arg)). Esto marca la navegación como una transición, lo que permite a React mantener visible la interfaz actual mientras la acción se ejecuta en el servidor.

Los Server Actions son el lugar adecuado para realizar la validación en el servidor. Valide los campos de FormData, devuelva errores de validación si no son válidos y continúe con la mutación únicamente si todos los campos son correctos. Las bibliotecas como Zod se integran bien en este caso: analice FormData con un esquema tipado y devuelva el mapa de errores si se produce un fallo.

Los Server Actions sustituyen el patrón de fetch + ruta de API para las mutaciones de formularios. La propiedad action del formulario acepta directamente un Server Action, que recibe un objeto FormData. Las acciones devuelven resultados serializables para actualizar la interfaz del cliente, admiten revalidatePath y revalidateTag para invalidar la caché y funcionan progresivamente sin JavaScript.