React
Explica cómo las Actions y useActionState coordinan mutaciones asíncronas, resultados, errores y estado pendiente alrededor del envío de formularios.
React permite pasar funciones a y . La transición pendiente y el reset del formulario pueden integrarse con el flujo.
actionformActionasync function createUser(formData: FormData) {
const email = String(formData.get("email"));
await api.createUser({ email });
}
<form action={createUser}>
<input name="email" />
<button>Crear</button>
</form>Permite que una Action produzca estado para el siguiente render.
const [result, submitAction, isPending] = useActionState(
async (_previous, formData: FormData) => {
try {
await createUser(formData);
return { error: null };
} catch {
return { error: "No fue posible crear el usuario" };
}
},
{ error: null },
);<form action={submitAction}>
<input name="email" />
<button disabled={isPending}>
{isPending ? "Creando..." : "Crear"}
</button>
{result.error && <p>{result.error}</p>}
</form>Una Action no elimina validación, autorización, idempotencia ni manejo de errores del servidor.
FormData como datos confiables.Actions modelan mutaciones y estados pendientes como parte del árbol React.
Una Action es una función que participa en una transición asíncrona de React. Puede pasarse a action de un formulario o ejecutarse dentro de una transition. React coordina pending, errores compatibles y actualización del árbol.
submit
↓
Action recibe FormData
↓
validación y mutación
↓
resultado para siguiente renderNo confundas una Action de React con una action de Redux ni con una API endpoint. Es una función de mutación bajo un flujo integrado.
Cuando el framework y el entorno lo permiten, un formulario con action puede conservar semántica nativa y funcionar antes de que termine la hidratación. La capacidad exacta depende de si la función vive en cliente o servidor y de la infraestructura utilizada.
Mantén:
name en controles.const [state, formAction, isPending] = useActionState(
async (previousState, formData: FormData) => {
// validar y mutar
return nextState;
},
initialState,
);La función recibe primero el estado anterior y luego los argumentos normales de la Action. Esto cambia la firma respecto a pasar la Action directamente al formulario.
type CreateUserState =
| { status: "idle"; fieldErrors: {} }
| { status: "error"; fieldErrors: Record<string, string>; message?: string }
| { status: "success"; userId: string };Devuelve información serializable y útil para el siguiente render. No devuelvas excepciones internas, tokens ni detalles sensibles.
async function createUserAction(
_previous: CreateUserState,
formData: FormData,
): Promise<CreateUserState> {
const email = String(formData.get("email") ?? "").trim();
if (!isValidEmail(email)) {
return {
status: "error",
fieldErrors: { email: "Ingresa un correo válido" },
};
}
const user = await userService.create({ email });
return { status: "success", userId: user.id };
}TypeScript no valida FormData en runtime. Convierte, verifica y autoriza dentro del límite confiable.
isPending pertenece a la Action asociada al Hook. Para componentes descendientes de un formulario, useFormStatus permite conocer el submit concreto. Los botones con formAction pueden disparar mutaciones distintas; diseña etiquetas y estados que expliquen cuál está pendiente.
Devuelve errores esperados de negocio como state. Los errores inesperados pueden lanzarse para una Error Boundary según la arquitectura:
No conviertas todo fallo en un string indistinguible.
Un formulario no controlado puede resetearse tras una Action exitosa. Si existen campos controlados, su state continúa necesitando actualización. No asumas que Action borra cualquier estado de React.
Cuando una Action se ejecuta en servidor:
"use server" marca funciones bajo una integración compatible; no convierte un componente completo en servidor.
Varias ejecuciones pueden solaparse. Evita que una respuesta antigua reemplace estado más reciente o que dos submits creen duplicados. El servidor debe resolver consistencia; el cliente comunica pending y bloquea acciones incompatibles cuando corresponda.
Prueba la Action como función cuando sea posible y el formulario por comportamiento:
useActionState transforma el resultado de una Action en state.FormData requiere validación runtime.useActionState?useState u otro store.useFormStatus y useOptimistic profundiza en pending descendiente y representación temporal de resultados esperados.