¿Qué ocurre internamente cuando se asigna una Server Action al atributo action de un ?

El compilador remueve el cuerpo de la función del bundle del cliente, genera un endpoint RPC y provee una referencia con el Action ID. Al enviar el formulario, React intercepta el evento y realiza una petición POST con la cabecera Next-Action y el cuerpo FormData. Si el JavaScript aún no ha cargado o está desactivado, el navegador emite un POST nativo que Next.js procesa en el backend.

¿Por qué las Server Actions NO deben utilizarse para recibir webhooks de Stripe o GitHub?

Las Server Actions dependen de la cabecera Next-Action y aplican validación Origin vs Host (protección CSRF). Los emisores externos de webhooks despachan peticiones POST genéricas sin estas cabeceras especiales. Los webhooks deben recibirse a través de Route Handlers tradicionales (route.ts).

¿En qué se diferencia useActionState de useState al gestionar mutaciones?

useActionState (React 19) está diseñado específicamente para Server Actions. Retorna la tupla [state, formAction, isPending]. Suprime el código repetitivo de try/catch, gestiona automáticamente el estado isPending, recibe el estado previo (prevState) y soporta Progressive Enhancement antes de la hidratación.

¿Por qué llamar a redirect() dentro de un bloque try/catch en una Server Action causa un comportamiento anómalo?

redirect() de next/navigation funciona emitiendo una excepción interna NEXT_REDIRECT. Si se ubica dentro de un bloque try/catch genérico, este intercepta la excepción como si fuera un error, impidiendo que el servidor envíe la cabecera de redirección. redirect() debe colocarse siempre fuera de los bloques try/catch.

¿Cómo se dispara una Server Action de manera programática fuera de un formulario?

Se ejecuta dentro del hook useTransition de React 19 invocando startTransition(async () => { await myAction(data); }). La variable isPending devuelta por useTransition permite coordinar spinners de carga y deshabilitar controles interactivos.

¿De qué modo defienden las Server Actions contra ataques CSRF de forma automática?

Next.js analiza las cabeceras Origin o Referer de la petición POST entrante y las compara con la cabecera Host del servidor de destino. Si no coinciden, la petición es denegada de inmediato con un estado 403 Forbidden. Se pueden admitir dominios externos mediante serverActions.allowedOrigins en next.config.ts.

¿Cuál es la diferencia entre capturar variables mediante clausuras y pasarlas vía .bind()?

En acciones en línea, la clausura captura y cifra todas las variables del ámbito exterior del componente, transmitiéndolas al cliente en la referencia proxy. Con .bind(null, arg), se vinculan exclusivamente los parámetros escalares requeridos, impidiendo la exposición innecesaria de objetos confidenciales.

¿Cómo consiguen las Server Actions retornar la UI actualizada en una única respuesta HTTP?

Al invocarse revalidatePath o revalidateTag, Next.js no exige una petición GET complementaria. Dentro del canal HTTP ya abierto, ejecuta la mutación, purga la caché, re-renderiza el árbol de Server Components afectado y emite una respuesta unificada con el resultado de la acción y el nuevo RSC Flight Payload.

Server Actions: Mutaciones de datos y manejo de formularios — Next.js 16 App Router

Por qué es importante#

En el desarrollo web cliente-servidor convencional, ejecutar mutaciones de datos exigía una notable cantidad de código de infraestructura. El desarrollador debía crear un endpoint REST o GraphQL específico, configurar manejadores onSubmit en el cliente, instanciar clientes HTTP, supervisar estados de carga mediante useState, gestionar errores de red y purgar manualmente las cachés del cliente.

En el App Router de Next.js y React 19 se implementa el concepto de Server Actions: funciones asíncronas de servidor que se invocan directamente desde componentes de cliente o se asignan al atributo action de formularios HTML nativos.

Ventajas fundamentales de la arquitectura de Server Actions:

Progressive Enhancement: Los formularios se procesan de manera nativa sin requerir que la hidratación de React haya concluido en conexiones lentas.
Eliminación del boilerplate de API: Se erradica la necesidad de mantener Route Handlers independientes para mutaciones internas de la interfaz.
Seguridad de tipos extremo a extremo (End-to-End TypeScript): Los argumentos y valores devueltos por las funciones se tipifican directamente sin herramientas intermedias.
Mutación en un único salto (Single-Roundtrip Mutation): La modificación en la base de datos, la invalidación de caché (revalidatePath / revalidateTag) y el re-renderizado del árbol de Server Components se consolidan en una sola respuesta HTTP.

Modelo mental#

Las Server Actions se fundamentan en la directiva 'use server'. Esta directiva señala al compilador de Next.js (Turbopack) que la función o módulo en cuestión debe ejecutarse exclusivamente en el servidor.

Cuando se inyecta una Server Action en un Client Component, el compilador excluye el cuerpo de la función del bundle de JavaScript del navegador. En su lugar, genera un identificador criptográfico único (Action ID) e inicializa una referencia proxy ligera en el cliente.

Al ejecutarse la acción, el navegador despacha de forma transparente una petición HTTP POST que incluye la cabecera personalizada Next-Action. El servidor procesa la lógica de negocio y emite la respuesta serializada.

Desde el punto de vista conceptual, las Server Actions constituyen una implementación de la arquitectura RPC, integrada de manera nativa en el árbol de componentes de React.

Ciclo de vida de una llamada de red con Server Action

1. Inicialización de la mutaciónClient

El usuario envía un formulario o ejecuta la acción programáticamente mediante un transition.

Con JS activo, se intercepta el evento sintético; sin JS, se emite un envío POST nativo de formulario.

2. Emisión vía Next-ActionNetwork

El navegador remite la petición POST con el cuerpo FormData y el Action ID en la cabecera.

POST /posts HTTP/1.1 Next-Action: 7f8b9c2d1e0a4f5b6c7d8e9f

3. Verificación de seguridad (Origin vs Host)Security

Next.js valida el origen de la petición para mitigar ataques CSRF de forma automática.

Si las cabeceras Origin y Host difieren, el servidor responde inmediatamente con un código 403 Forbidden.

4. Descifrado y ejecuciónServer Execution

El servidor descifra los parámetros vinculados vía .bind(), verifica la sesión y ejecuta la consulta SQL.

5. Revalidación de caché y re-renderizadoCache & RSC

La invocación de revalidatePath purga la caché y re-renderiza al instante los Server Components afectados.

6. Reconciliación DOM en un solo round-tripReconciliation

El cliente recibe el resultado de la acción y el nuevo RSC Flight Payload en el mismo cuerpo de respuesta.

React actualiza los componentes en el DOM de forma suave sin requerir recargar la página.

Sintaxis y API#

1. La directiva 'use server'#

Las Server Actions pueden estructurarse de dos maneras:

Acciones en línea (Inline): Declaradas en el cuerpo de un Server Component.
Acciones a nivel de módulo (Module-level): Ubicadas en archivos dedicados que exportan funciones de servidor.

tsxServer Action en línea en Server Component (app/posts/page.tsx)

import { db } from '@/lib/db';
import { posts } from '@/lib/schema';
import { revalidatePath } from 'next/cache';

export default function PostsPage() {
  // Función asíncrona dentro de un Server Component
  async function createPost(formData: FormData): Promise<void> {
    'use server'; // La directiva al inicio del cuerpo marca la función como Server Action
    
    const title = formData.get('title');
    if (typeof title !== 'string' || !title.trim()) {
      return;
    }

    await db.insert(posts).values({ title });
    
    // Invalida la caché para reflejar de inmediato la nueva publicación
    revalidatePath('/posts');
  }

  return (
    <main className="p-6">
      <form action={createPost} className="flex gap-2">
        <input type="text" name="title" required className="border p-2 rounded" />
        <button type="submit" className="bg-blue-600 text-white px-4 py-2 rounded">
          Crear publicación
        </button>
      </form>
    </main>
  );
}

Para consumir acciones dentro de Client Components ('use client'), estas deben residir obligatoriamente en un archivo separado con la directiva 'use server' en su encabezado:

tsxServer Actions modulares (app/actions/posts.ts)

'use server'; // Aplica a todas las funciones exportadas en este módulo

import { db } from '@/lib/db';
import { posts } from '@/lib/schema';
import { eq } from 'drizzle-orm';
import { revalidatePath } from 'next/cache';

export async function deletePostAction(postId: string): Promise<{ success: boolean }> {
  await db.delete(posts).where(eq(posts.id, postId));
  revalidatePath('/posts');
  return { success: true };
}

2. El hook useActionState (React 19)#

Para coordinar el estado de un formulario, gestionar fallos de validación y mostrar estados de carga en React 19, se emplea el hook useActionState.

tsxControl del estado del formulario con useActionState (components/UserForm.tsx)

'use client';

import { useActionState } from 'react';
import { createUserAction, type FormState } from '@/app/actions/users';

const initialState: FormState = {
  success: false,
  message: '',
  errors: undefined,
};

export function UserForm() {
  // state — estado actual devuelto por la acción
  // formAction — función intermediaria suministrada a <form action={...}>
  // isPending — bandera booleana que refleja la ejecución de la petición
  const [state, formAction, isPending] = useActionState(createUserAction, initialState);

  return (
    <form action={formAction} className="space-y-4 max-w-md">
      <div>
        <label htmlFor="email" className="block text-sm font-medium">Correo electrónico</label>
        <input
          id="email"
          name="email"
          type="email"
          required
          className="w-full border rounded p-2"
        />
        {state.errors?.email && (
          <p className="text-red-500 text-xs mt-1">{state.errors.email[0]}</p>
        )}
      </div>

      <button
        type="submit"
        disabled={isPending}
        className="w-full bg-blue-600 text-white py-2 rounded disabled:opacity-50"
      >
        {isPending ? 'Guardando...' : 'Registrar usuario'}
      </button>

      {state.message && (
        <p className={`text-sm ${state.success ? 'text-green-600' : 'text-red-600'}`}>
          {state.message}
        </p>
      )}
    </form>
  );
}

3. El hook useFormStatus#

El hook useFormStatus de react-dom permite a los componentes descendientes consultar el estado de envío del formulario contenedor sin necesidad de props:

tsxBotón de envío aislado con useFormStatus (components/SubmitButton.tsx)

'use client';

import { useFormStatus } from 'react-dom';

export function SubmitButton({ label = 'Enviar' }: { label?: string }) {
  // Lee el contexto del formulario <form> ancestro más cercano
  const { pending, data, method } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      className="px-4 py-2 rounded bg-accent-cyan text-black font-semibold disabled:opacity-50 transition-opacity"
    >
      {pending ? 'Procesando...' : label}
    </button>
  );
}

4. Actualizaciones optimistas mediante useOptimistic#

El hook useOptimistic permite proyectar modificaciones de estado en la UI de inmediato antes de que el servidor confirme la petición:

tsxContador optimista de me gusta (components/LikeButton.tsx)

'use client';

import { useOptimistic, startTransition } from 'react';
import { likePostAction } from '@/app/actions/posts';

interface LikeButtonProps {
  postId: string;
  initialLikes: number;
}

export function LikeButton({ postId, initialLikes }: LikeButtonProps) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (currentLikes: number, increment: number) => currentLikes + increment
  );

  const handleLike = () => {
    startTransition(async () => {
      // 1. Reflejar inmediatamente el cambio en el cliente de forma optimista
      addOptimisticLike(1);
      // 2. Emitir la petición al servidor
      await likePostAction(postId);
    });
  };

  return (
    <button
      type="button"
      onClick={handleLike}
      className="border border-border px-3 py-1.5 rounded-lg hover:border-accent-cyan"
    >
      Me gusta: {optimisticLikes}
    </button>
  );
}

PUNTO DE CONTROL

Control de comprensión: Mecánica de redirect() en Server Actions

+15 XP

¿Por qué invocar redirect('/dashboard') dentro de un bloque try { ... redirect('/dashboard') } catch (err) { ... } en una Server Action detiene la navegación?

Patrones prácticos#

Patrón 1: Transferencia de argumentos adicionales vía `.bind()`#

Al enviarse, un formulario HTML entrega únicamente el objeto FormData. Si la acción precisa de un parámetro contextual complementario (como el identificador de un registro), se recurre a .bind():

tsxVinculación de argumentos con .bind (components/UserList.tsx)

'use client';

import { deleteUserAction } from '@/app/actions/users';

interface UserDTO {
  id: string;
  name: string;
}

interface UserListProps {
  user: UserDTO;
}

export function UserItem({ user }: UserListProps) {
  // Vinculamos el argumento userId como primer parámetro de la Server Action
  const deleteWithUserId = deleteUserAction.bind(null, user.id);

  return (
    <div className="flex items-center justify-between p-3 border rounded">
      <span>{user.name}</span>
      <form action={deleteWithUserId}>
        <button type="submit" className="text-red-500 hover:underline">
          Eliminar
        </button>
      </form>
    </div>
  );
}

Patrón 2: Autenticación y control de acceso (RBAC)#

[!IMPORTANT] Las Server Actions son endpoints RPC públicos. Toda acción exportada puede invocarse directamente mediante peticiones HTTP POST desde herramientas externas (cURL, Postman). Ocultar un botón en la interfaz de usuario no protege la acción. La verificación de sesión y permisos (RBAC) es estrictamente obligatoria en la primera línea de cada Server Action.

tsxAutenticación en Server Action con cookies asíncronas (app/actions/admin.ts)

'use server';

import { cookies } from 'next/headers';
import { verifySessionToken } from '@/lib/auth';

export async function executeAdminTask(data: FormData): Promise<{ success: boolean; error?: string }> {
  // Lectura asíncrona de cookies conforme al estándar de Next.js 15+
  const cookieStore = await cookies();
  const token = cookieStore.get('session_token')?.value;

  if (!token) {
    return { success: false, error: 'Unauthorized: Sesión inexistente' };
  }

  const session = await verifySessionToken(token);
  if (!session || session.role !== 'admin') {
    return { success: false, error: 'Forbidden: Privilegios insuficientes' };
  }

  // Lógica de negocio del administrador...
  return { success: true };
}

PUNTO DE CONTROL

Control de comprensión: Seguridad y serialización de clausuras

+15 XP

Un Server Component recupera de la BD un usuario con 150 campos (incluyendo passwordHash). Dentro del componente se define una acción en línea: async function update() { 'use server'; await db.save(user.id); }. ¿Qué riesgo de seguridad se suscita?

Errores frecuentes#

Ошибка: Capturar la excepción NEXT_REDIRECT dentro de bloques try/catch

La función redirect() de next/navigation arroja intencionadamente una excepción interna (NEXT_REDIRECT) para abortar el renderizado en curso y despachar la cabecera de redirección.

Si se encierra redirect() dentro de un bloque try/catch convencional, la excepción se confunde con un error de aplicación, abortando la navegación:

Solución: Sitúa siempre las llamadas a redirect() después del bloque try/catch.

tsxLlamada correcta a redirect()

// ❌ ERROR: redirect es interceptado por el bloque catch
'use server';
import { redirect } from 'next/navigation';

export async function createPostAction(prevState: unknown, formData: FormData) {
  try {
    await db.insert(posts).values({ title: formData.get('title') });
    redirect('/posts'); // ¡Arroja la excepción NEXT_REDIRECT!
  } catch (err: unknown) {
    // ¡La redirección se captura aquí, mostrando un error en vez de navegar!
    return { error: 'No se pudo crear la publicación' };
  }
}

// ✅ CORRECTO: Invocar redirect fuera del bloque try/catch
export async function createPostAction(prevState: unknown, formData: FormData) {
  try {
    await db.insert(posts).values({ title: formData.get('title') });
  } catch (err: unknown) {
    return { error: 'No se pudo crear la publicación' };
  }
  
  redirect('/posts'); // Se ejecuta limpiamente fuera del interceptor
}

Ошибка: La falsa presunción de privacidad: las Server Actions son públicas

Una Server Action señalada con 'use server' está disponible para cualquier cliente que conozca su Action ID. Aunque un botón se oculte condicionalmente en la interfaz para usuarios corrientes, un usuario malintencionado puede enviar una petición POST directa con la cabecera Next-Action y ejecutar la operación.

Solución: Los controles de acceso (RBAC) deben validarse dentro de la función en el servidor antes de cualquier modificación.

Ошибка: Serialización inadvertida de clausuras pesadas (Closures)

Al declarar Server Actions en línea dentro de Server Components, el compilador cifra y envía al navegador todas las variables del componente padre capturadas en el ámbito.

Solución: Declara las acciones en módulos dedicados actions.ts y suministra únicamente los valores primitivos necesarios mediante .bind().

tsxAislamiento de acciones respecto al contexto del componente

// ❌ PELIGROSO: Captura el objeto heavyUser completo con información privada
export default async function ProfilePage() {
  const heavyUser = await db.getUser(); // Contiene passwordHash, secretKeys, 100 atributos

  async function updateStatus() {
    'use server';
    // Aunque solo se emplee el id, ¡Next.js cifrará y enviará al cliente TODO el objeto heavyUser!
    await db.updateUserStatus(heavyUser.id, 'online');
  }

  return <form action={updateStatus}><button>Conectar</button></form>;
}

// ✅ CORRECTO: Exporta las acciones en actions.ts y envía únicamente IDs escalares
// app/actions.ts:
// export async function updateStatus(userId: string) { 'use server'; ... }

Matriz comparativa: Server Actions frente a Route Handlers#

Server Actions frente a Route Handlers (API Routes)

Критерий	Server Actions ('use server')	Route Handlers (route.ts)
Propósito principal	Mutaciones desde la interfaz, envío de formularios, llamadas RPC internas	APIs REST públicas para aplicaciones móviles, servicios de terceros y webhooks
Integración con la UI	Nativa: useActionState, useOptimistic, envíos estándar de formularios HTML	Manual: demanda fetch(), useEffect/TanStack Query y orquestación de estado
Invalidación de caché	Re-renderizado automático de RSC en un único salto con revalidatePath/Tag	Demanda ejecutar router.refresh() de forma explícita en el cliente
Mitigación CSRF	Incorporada por defecto (comprobación estricta de Origin frente a Host)	Desactivada por defecto; requiere gestión manual de tokens y cabeceras
Progressive Enhancement	Soportada de forma nativa (los formularios operan incluso sin JavaScript)	No soportada sin la intervención de JavaScript en el cliente

Preguntas de entrevista#

Preguntas de entrevista8 preguntas

Temas relacionados

Caché y revalidación: Los 4 niveles de caché de Next.js Validación de formularios: Zod, Server Actions y formularios tipificados Route Handlers: REST API, Streaming y Webhooks Data Fetching en Next.js: RSC, React cache y Data Access Layer

Server Actions: Mutaciones de datos y manejo de formularios

Por qué es importante#

Modelo mental#

Sintaxis y API#

1. La directiva 'use server'#

2. El hook useActionState (React 19)#

3. El hook useFormStatus#

4. Actualizaciones optimistas mediante useOptimistic#

Patrones prácticos#

Patrón 1: Transferencia de argumentos adicionales vía .bind()#

Patrón 2: Autenticación y control de acceso (RBAC)#

Errores frecuentes#

Ошибка: Capturar la excepción NEXT_REDIRECT dentro de bloques try/catch

Ошибка: La falsa presunción de privacidad: las Server Actions son públicas

Ошибка: Serialización inadvertida de clausuras pesadas (Closures)

Matriz comparativa: Server Actions frente a Route Handlers#

Preguntas de entrevista#

Por qué es importante#

Modelo mental#

Sintaxis y API#

1. La directiva 'use server'#

2. El hook useActionState (React 19)#

3. El hook useFormStatus#

4. Actualizaciones optimistas mediante useOptimistic#

Patrones prácticos#

Patrón 1: Transferencia de argumentos adicionales vía .bind()#

Patrón 2: Autenticación y control de acceso (RBAC)#

Errores frecuentes#

Ошибка: Capturar la excepción NEXT_REDIRECT dentro de bloques try/catch

Ошибка: La falsa presunción de privacidad: las Server Actions son públicas

Ошибка: Serialización inadvertida de clausuras pesadas (Closures)

Matriz comparativa: Server Actions frente a Route Handlers#

Preguntas de entrevista#

Patrón 1: Transferencia de argumentos adicionales vía `.bind()`#

Patrón 1: Transferencia de argumentos adicionales vía `.bind()`#