Server Actions
Prioridad: P1 (ALTA)
[!WARNING] Si el proyecto utiliza el directorio
pages/en lugar del App Router, ignora este skill por completo.
Maneja envíos de formularios y mutaciones sin crear endpoints de API.
Guías de Implementación
-
Directiva: Siempre comienza el archivo o la función con
'use server'. UsaformData.get('title')para acceder a campos de formulario tipados. Exporta funciones asíncronas para mutaciones. -
Manejo de Formularios: Usa la propiedad
actionde<form>para activar acciones medianteaction={createPost}. UtilizauseFormStatus()para estadospending—disabled={pending}en botones. UsauseActionState(React 19/Next.js 15) para el estado del formulario conaction={action}y<form action={action}>. -
Actualización de Datos: Activa actualizaciones de UI usando
revalidatePath('/')orevalidateTag('tag-name')después de una mutación exitosa. -
Interactividad: Para desencadenantes que no son formularios, invoca acciones usando el hook
useTransitionpara manejar la UI de carga y evitar que la página se bloquee. -
Actualizaciones Optimistas: Usa
useOptimisticpara mostrar el estado esperado de la UI de inmediato antes de que el servidor confirme la mutación. -
Seguridad: Sanitiza todas las entradas de
FormData. Realiza verificaciones de autenticación dentro de cada acción (await auth()). Limita la subida de archivos por tamaño y tipo MIME. -
Formulario:
<form action={createPost}>(las mejoras progresivas funcionan sin JS). -
Manejador de Eventos:
onClick={() => createPost(data)}. -
Estado Pendiente: Usa el hook
useFormStatus(debe estar dentro de un componente renderizado dentro del formulario).
P1: Estándar Operativo
1. Asegurar y Validar
Siempre valida las entradas con un esquema z.object({ y safeParse antes de procesar. Verifica la autorización dentro de la acción. Consulta el Ejemplo de Acción Segura.
2. Estados Pendientes
Usa useActionState (React 19/Next.js 15+) para el manejo de estados y useFormStatus para los estados de carga de botones.
Restricciones
- Clausuras: Evita definir acciones dentro de componentes para prevenir la sobrecarga de cifrado de clausuras ocultas y errores de serialización.
- Redirección: Usa
redirect()para navegación exitosa; lanza un error que Next.js captura para manejar la redirección.
Anti-Patrones
- No usar entradas de Server Action sin validar: Siempre valida con Zod antes de procesar.
- No saltar verificaciones de autenticación: Verifica la sesión/usuario dentro de cada acción, no solo en middleware.
- No definir acciones dentro de componentes: Defínelas en
actions.tspara evitar errores de clausura. - No usar
redirect()dentro de try/catch:redirect()lanza un error; capturarlo suprime la redirección.