¿Cómo debe estructurarse el uso de React Context en una aplicación dominada por Server Components?

Se crea un Client Component específico (como Providers.tsx con 'use client') que renderice el Context.Provider con el slot {children}. En el Root Layout del servidor se utiliza este componente como envoltura. Al transferirse los componentes secundarios vía children, estos conservan su naturaleza de Server Components y se excluyen del bundle del cliente.

¿En qué consiste el Donut Pattern en React Server Components y qué problema arquitectónico resuelve?

El Donut Pattern permite renderizar componentes pesados de servidor dentro de una estructura interactiva de cliente sin incluir el código del servidor en el bundle de JavaScript del navegador. El Client Component recibe los elementos hijos vía props (children o slots nombrados), mientras que la instanciación y ejecución del componente de servidor ocurren externamente en el componente padre del servidor.

¿Qué es el 'Module Poisoning' (envenenamiento de módulos) en Next.js?

Es la situación en la que la importación accidental de un módulo o librería de servidor en un archivo con 'use client' obliga al compilador a empaquetar código de servidor para el cliente. Esto provoca una sobrecarga masiva del bundle o fallos de compilación debido a la ausencia de APIs de Node.js (fs, net, process.env).

¿Cómo ayuda el patrón de Named Slots a organizar interfaces complejas de cliente?

En lugar de limitarse a una sola prop children, el Client Component define múltiples props de tipo React.ReactNode (por ejemplo: header, sidebar, content). El componente padre del servidor suministra bloques independientes a cada ranura, permitiendo gestionar el diseño y la interactividad sin acoplar estados de servidor y cliente.

¿Por qué se recomienda ubicar los proveedores de contexto (Context Providers) lo más abajo posible en el árbol?

Aunque envolver Server Components en un proveedor no los convierte en clientes, las actualizaciones del valor del contexto desencadenan re-renderizados en todos los consumidores clientes (useContext). Colocar los proveedores cerca de las hojas aísla los re-renders al subárbol afectado y alivia la carga en el hilo principal del navegador.

¿Por qué pasar un componente vía {children} preserva su estado de servidor, mientras que un import directo lo convierte en cliente?

El import directo crea una dependencia estática en el grafo de módulos del compilador, obligando a empaquetar el archivo importado para el navegador. En la composición vía children, el componente de servidor se importa y evalúa en un archivo de servidor. El cliente recibe únicamente el descriptor JSX serializado (Flight Payload), mostrando el resultado sin necesidad de descargar el código fuente de la función.

¿Se pueden pasar funciones desde un Server Component a un Client Component mediante props?

Las funciones síncronas convencionales y clausuras no se pueden transferir porque no son serializables en el protocolo JSON/Flight. Sin embargo, sí está permitido pasar Server Actions (funciones con 'use server'), las cuales se serializan como identificadores RPC seguros para ejecutar mutaciones.

¿Qué riesgo presentan los archivos Barrel (index.ts) al interactuar con 'use client'?

Si un Client Component importa una entidad desde index.ts, el empaquetador puede inspeccionar todas las reexportaciones. Si en ese mismo archivo se reexportan componentes de servidor pesados o librerías del backend, el tree-shaking puede degradarse, arrastrando código de servidor al bundle del cliente.

Patrones de composición en Next.js: Interleaving y Donut Pattern — Next.js 16 App Router

Por qué es importante#

Con la llegada de la arquitectura React Server Components (RSC), los desarrolladores se enfrentaron a un desafío fundamentalmente nuevo: dividir una base de código común a través de los límites físicos del servidor y el cliente dentro del mismo árbol visual de interfaz.

En React tradicional, la composición de componentes era trivial: cualquier componente podía importar libremente cualquier otro archivo. En Next.js App Router rigen límites de red físicos estrictos (Network Boundary). Los fallos en el diseño arquitectónico conducen a:

Module Poisoning (Envenenamiento de módulos) y una sobrecarga desmesurada del JavaScript del cliente.
Errores en tiempo de compilación al intentar invocar APIs de Node.js (fs, controladores de bases de datos, tokens privados) dentro del bundle del navegador.
Imposibilidad de utilizar hooks de estado (useState, useEffect) o React Context sin perder las ventajas inherentes del servidor.

Los patrones de composición representan un conjunto riguroso de soluciones arquitectónicas que permiten intercalar componentes de servidor y cliente (Interleaving), mantener el tamaño del bundle del cliente cercano a cero y transferir datos a través del límite de red sin violar las reglas de aislamiento de RSC.

Modelo mental#

En Next.js, la raíz del árbol de componentes (layout.tsx, page.tsx) siempre se ejecuta en el servidor.

La regla del compilador Turbopack es categórica: la directiva 'use client' infecta en cascada todo su subárbol de importaciones. Si importas un componente en un archivo marcado con 'use client', ese componente (y todas sus dependencias transitivas) se compilan automáticamente para el bundle del cliente.

Visualizador de Límites de Componentes Servidor y Cliente

Inspeccione los límites de serialización de React Flight y el impacto de 'use client' en el bundle

Jerarquía de Renderizado de ComponentesBundle: ~3.2 KB (Solo el botón interactivo)

ProductPage.tsxServer Component (Acceso directo por SQL a la BD)

Server (0 KB JS)

ProductDetails.tsxServer Component (Renderiza la descripción pesada)

Server (0 KB JS)

⚡ Límite de React Flight Serialization

AddToCartBtn.tsx

'use client' (Hook useState, evento onClick)Client (+3.2 KB JS)

ReviewFeed.tsx

Server Component (Consulta SQL directa de reseñas)Server (0 KB JS)

Diagnóstico de Patrón Arquitectónico:

Aislamiento en Hojas (Leaf-Level 'use client')

La directiva 'use client' se coloca en la hoja interactiva (el botón). Los datos y parsers pesados se ejecutan en el servidor y no entran en el bundle JS.

Reglas de Serialización de Props a través del Límite:

productId: 'sku-90' (JSON string)

price: 19900 (JSON number)

onClick: () => void (¡Funciones estrictamente prohibidas!)

Regla de Oro de RSC: Desplace la directiva 'use client' lo más profundo posible en el árbol de componentes.

El principio rector para los arquitectos de Fullstack Agentic Lab: empujar 'use client' lo más cerca posible de las hojas del árbol, y cuando el contenido del servidor deba residir dentro de un contenedor interactivo de cliente, emplear el Donut Pattern (Patrón del dónut).

Matriz de compatibilidad de relaciones entre componentes

1. Server Component -> Server Componentserver

Permitido directamente vía import. Se ejecuta estrictamente en el servidor; 0 KB en el bundle del navegador.

2. Server Component -> Client Componentboundary

Permitido directamente vía import. Las props deben ser serializables (tipos JSON, Promises, slots JSX).

3. Client Component -> Client Componentclient

Permitido directamente vía import. Árbol de React convencional ejecutándose en el navegador.

4. Client Component -> Server Component (Importación directa)forbidden

Estrictamente prohibido. La importación directa fuerza al compilador a incluir el Server Component en el bundle del cliente.

5. Client Component -> Server Component (Vía Slots / Children)donut

Permitido. Donut Pattern: el Server Component se evalúa externamente en el servidor y se inyecta como descriptor ReactNode.

PUNTO DE CONTROL #1

Control de comprensión: Envenenamiento en cascada del bundle del cliente

+15 XP

¿Qué ocurre si un Client Component (declarado con 'use client') importa directamente un Server Component: import { ServerFeed } from './ServerFeed'?

Sintaxis y API#

1. El patrón del agujero del dónut (Donut Pattern / Children Slot)#

Cuando un componente interactivo de cliente (como una barra lateral plegable con animación) necesita renderizar en su interior datos pesados del servidor, utilizamos la prop children:

tsxcomponents/CollapsibleSidebar.tsx (Client Component)

'use client';

import { useState } from 'react';

interface CollapsibleSidebarProps {
  children: React.ReactNode; // Slot del servidor
}

export function CollapsibleSidebar({ children }: CollapsibleSidebarProps) {
  const [isOpen, setIsOpen] = useState(true);

  return (
    <div className="flex">
      <aside className={`transition-all duration-300 ${isOpen ? 'w-64' : 'w-16'}`}>
        <button 
          type="button" 
          onClick={() => setIsOpen(!isOpen)}
          className="p-2 border border-border rounded bg-bg-elevated text-xs mb-4"
        >
          {isOpen ? 'Plegar' : 'Desplegar'}
        </button>

        {/* Aquí se renderiza el nodo del servidor evaluado. ¡El código de BD no entra al bundle! */}
        <div className={isOpen ? 'block' : 'hidden'}>
          {children}
        </div>
      </aside>
    </div>
  );
}

tsxapp/dashboard/page.tsx (Server Component)

import { CollapsibleSidebar } from '@/components/CollapsibleSidebar';
import { ServerNavigationTree } from '@/components/ServerNavigationTree'; // Librería de servidor + consulta BD

export default async function DashboardPage() {
  return (
    <main className="p-8">
      <h1 className="text-2xl font-bold mb-6">Panel de control</h1>

      {/* Donut Pattern: inyectamos el Server Component dentro del contenedor de cliente */}
      <CollapsibleSidebar>
        <ServerNavigationTree />
      </CollapsibleSidebar>
    </main>
  );
}

2. Patrón de slots nombrados (Named Slots Pattern)#

Si la interfaz requiere estructurarse en varias zonas independientes (por ejemplo, cabecera, barra lateral y área de contenido), el Client Component declara Named Slots (Ranuras con nombre):

tsxcomponents/SplitLayout.tsx (Client Component con múltiples slots)

'use client';

import { useState } from 'react';

interface SplitLayoutProps {
  sidebarSlot: React.ReactNode;
  contentSlot: React.ReactNode;
}

export function SplitLayout({ sidebarSlot, contentSlot }: SplitLayoutProps) {
  const [activePane, setActivePane] = useState<'both' | 'content'>('both');

  return (
    <div className="flex gap-6 min-h-screen">
      {activePane === 'both' && (
        <aside className="w-1/3 border-r border-border p-4">
          <button 
            type="button" 
            onClick={() => setActivePane('content')} 
            className="text-xs text-accent-cyan mb-3 block"
          >
            Enfocar contenido →
          </button>
          {sidebarSlot}
        </aside>
      )}

      <section className="flex-1 p-4">
        {activePane === 'content' && (
          <button 
            type="button" 
            onClick={() => setActivePane('both')} 
            className="text-xs text-accent-cyan mb-3 block"
          >
            ← Mostrar barra lateral
          </button>
        )}
        {contentSlot}
      </section>
    </div>
  );
}

3. Patrón de proveedores de contexto (Client Context con hijos del servidor)#

El hook useContext no está disponible en Server Components. Sin embargo, librerías esenciales (Next-Themes, TanStack Query, Zustand) exigen envolver la aplicación en un Context Provider.

Solución: aislar el proveedor en un Client Component dedicado que acepte {children}:

tsxcomponents/providers/AppProviders.tsx

'use client';

import { ThemeProvider } from 'next-themes';

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="dark" enableSystem>
      {/* ¡Todos los Server Components anidados conservan su ejecución de servidor! */}
      {children}
    </ThemeProvider>
  );
}

tsxapp/layout.tsx (Server Component)

import { AppProviders } from '@/components/providers/AppProviders';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="es" suppressHydrationWarning>
      <body className="bg-bg-base text-text-primary">
        {/* ¡El layout raíz del servidor sigue siendo un Server Component! */}
        <AppProviders>
          {children}
        </AppProviders>
      </body>
    </html>
  );
}

Comparación arquitectónica: Importación directa vs Composición vía Slots / Children

Критерий	Importación directa en 'use client'	Composición vía Slots / Children
¿Dónde se compila el componente?	En el Client Graph (se incluye en el bundle final del navegador)	En el Server Graph (el código se ejecuta estrictamente en el servidor)
Impacto en el tamaño del JS del cliente	Añade el peso de su código y de TODAS sus dependencias npm	0 KB de JavaScript en el bundle del navegador
Acceso a secretos y bases de datos	Prohibido (filtración al cliente o error de compilación fs/db)	Acceso total a BD, sistema de archivos y variables env privadas
¿Qué recibe el Client Component?	El código fuente de la función para ejecutarlo en el cliente	Un React Element Descriptor evaluado (nodo virtual DOM)
Comportamiento en re-renders	Se re-renderiza con cada cambio de estado del componente padre	Conserva el resultado del servidor; los cambios del padre no re-ejecutan children

Patrones prácticos#

Patrón 1: Desplazar el estado hacia abajo (Moving State Down)#

En lugar de declarar toda una página como cliente por culpa de un único campo de búsqueda, aísla la interactividad en un componente hoja:

tsxcomponents/SearchInput.tsx (Hoja interactiva de cliente)

'use client';

import { useTransition } from 'react';
import { useRouter, usePathname } from 'next/navigation';

export function SearchInput({ defaultValue = '' }: { defaultValue?: string }) {
  const router = useRouter();
  const pathname = usePathname();
  const [isPending, startTransition] = useTransition();

  const handleSearch = (term: string) => {
    const params = new URLSearchParams(window.location.search);
    if (term) {
      params.set('q', term);
    } else {
      params.delete('q');
    }
    startTransition(() => {
      router.replace(`${pathname}?${params.toString()}`);
    });
  };

  return (
    <div className="relative">
      <input
        type="search"
        defaultValue={defaultValue}
        placeholder="Buscar en la documentación..."
        onChange={(e) => handleSearch(e.target.value)}
        className="w-full px-4 py-2 rounded-lg bg-bg-elevated border border-border text-sm focus:outline-none focus:border-accent-cyan"
      />
      {isPending && <span className="absolute right-3 top-2.5 text-xs text-text-muted animate-spin">⏳</span>}
    </div>
  );
}

tsxapp/docs/page.tsx (Página de servidor)

import { SearchInput } from '@/components/SearchInput';
import { HeavyArticleList } from '@/components/HeavyArticleList'; // Server Component con analizador markdown

interface PageProps {
  searchParams: Promise<{ q?: string }>;
}

export default async function DocsPage({ searchParams }: PageProps) {
  const { q } = await searchParams;

  return (
    <div className="max-w-4xl mx-auto p-8 space-y-6">
      <h1 className="text-3xl font-bold">Base de conocimiento</h1>
      
      {/* Componente hoja interactivo de cliente */}
      <SearchInput defaultValue={q} />

      {/* Lista del servidor: 0 bytes de JS en el bundle del cliente */}
      <HeavyArticleList query={q ?? ''} />
    </div>
  );
}

Patrón 2: Pasar Server Actions vía props a botones interactivos#

Los botones de cliente pueden ejecutar mutaciones de servidor sin necesidad de crear manualmente Route Handlers (/api/...), recibiendo Server Actions como props:

tsxcomponents/ActionButton.tsx (Client Component)

'use client';

import { useTransition } from 'react';

interface ActionButtonProps {
  action: () => Promise<void>; // ¡Server Action transferida vía props!
  label: string;
}

export function ActionButton({ action, label }: ActionButtonProps) {
  const [isPending, startTransition] = useTransition();

  return (
    <button
      type="button"
      disabled={isPending}
      onClick={() => startTransition(async () => { await action(); })}
      className="px-4 py-2 rounded-lg bg-accent-violet text-white text-sm font-medium hover:bg-accent-violet/90 transition-colors disabled:opacity-50"
    >
      {isPending ? 'Ejecutando...' : label}
    </button>
  );
}

PUNTO DE CONTROL #2

Control de comprensión: Arquitectura interna del Donut Pattern

+15 XP

¿Por qué un Server Component pasado como children a un Client Component NO se vuelve a renderizar ni pierde su naturaleza de servidor cuando se ejecuta setState en el padre de cliente?

Errores frecuentes#

Ошибка: Intentar pasar funciones callback (onClick, onChange) desde un Server Component a un Client Component

Los Server Components no pueden pasar funciones síncronas convencionales en las props a Client Components porque las funciones no son serializables en el protocolo JSON/Flight de RSC (TypeError: Functions cannot be passed directly to Client Components).

Solución:

Si la función realiza una mutación de datos, utiliza una Server Action con la directiva 'use server' (serializada como identificador RPC seguro).
Si la lógica es meramente de interfaz (abrir un modal, cambiar de pestaña), declara el manejador dentro del propio Client Component.

tsxManejo adecuado de mutaciones con Server Actions

// ❌ ERROR: Función flecha síncrona definida dentro de un Server Component
// return <ClientButton onClick={() => console.log('delete')} />;

// ✅ CORRECTO: Utilizar una Server Action para mutaciones de servidor
// app/actions.ts:
// 'use server';
// export async function deleteItemAction(id: string) { await db.item.delete({ where: { id } }); }

// app/page.tsx:
// <ClientButton action={deleteItemAction} />

Ошибка: Sobrecarga del bundle de cliente por importaciones desde Barrel Files (index.ts)

Cuando un Client Component importa un botón sencillo desde un archivo barril común (import { Button } from '@/components'), el empaquetador puede incluir en el bundle del cliente componentes pesados de servidor (como el editor Monaco) que se reexportan en el mismo archivo.

Solución: Utiliza importaciones directas de módulo en archivos de cliente (import { Button } from '@/components/ui/Button') o configura optimizePackageImports en next.config.ts.

Ошибка: Declaración errónea de app/layout.tsx como Client Component para Theme/Auth Providers

Muchos desarrolladores agregan 'use client' directamente en app/layout.tsx para envolver la aplicación en ThemeProvider o SessionProvider. Este es un error arquitectónico crítico que convierte toda la aplicación en una SPA renderizada en el cliente, anulando las ventajas de RSC.

Solución: Crea un componente de cliente aislado AppProviders.tsx con la prop {children} y utilízalo dentro del RootLayout del servidor.

Ошибка: Omitir la protección server-only en módulos sensibles

Si un módulo accede a credenciales de base de datos pero no está protegido con import 'server-only', un miembro del equipo puede importarlo accidentalmente en un Client Component. Turbopack no fallará en compilación inicial y las variables secretas quedarán expuestas en el código del navegador.

Solución: Instala pnpm add server-only y añade import 'server-only' al comienzo de todos los archivos de servicios de datos sensibles.

Preguntas de entrevista#

Preguntas de entrevista8 preguntas

Temas relacionados

Componentes Server y Client en Next.js Inmersión profunda en React Flight Protocol Streaming SSR y Suspense en Next.js Partial Prerendering (PPR)