¿Cómo opera la navegación suave (Soft Navigation) en Next.js App Router por debajo?

Al hacer clic en un , el navegador evita recargar el documento completo. Dispara una petición fetch en segundo plano por el Flight Payload de la ruta destino (con la cabecera RSC: 1). React en el cliente procesa el flujo, descarga los paquetes de scripts que falten y ejecuta la reconciliación del DOM virtual, alterando únicamente los segmentos modificados y manteniendo intacto el estado de los componentes no afectados.

¿Tienen lugar rehidrataciones de Server Components durante la navegación suave?

No. Los Server Components carecen por completo de código JavaScript en el cliente y jamás se hidratan. El Reconciler del navegador toma directamente los nodos virtuales definidos en la línea 'J' del flujo Flight y los monta en el DOM. La hidratación se reserva exclusivamente para los componentes de cliente señalados por descriptores 'I'.

¿Qué ocurre ante un desajuste de versión (Version Skew) en plena navegación del usuario?

Si un usuario navega tras publicarse un nuevo despliegue, el Flight Payload devolverá referencias a hashes de JavaScript inexistentes en el cliente obsoleto. Al detectar el fallo de descarga o de manifiesto, Next.js recurre de manera automática a una Hard Navigation (recarga completa del documento), sincronizando limpiamente la sesión con la versión vigente.

¿Qué es el React Flight Protocol y en qué se diferencia sustancialmente del formato JSON clásico?

React Flight es un protocolo especializado en streaming para transferir árboles virtuales de componentes desde el servidor al cliente. A diferencia de JSON, Flight soporta referencias cíclicas, tipos nativos como Date, Map, Set y BigInt, jerarquías de elementos JSX, promesas en streaming no resueltas y descriptores de módulos de cliente (Client References) que mapean a los paquetes JS en el navegador.

¿Por qué no se pueden enviar funciones o callbacks comunes a través del Flight Protocol, mientras que las Server Actions sí están permitidas?

Las funciones corrientes dependen de clausuras de memoria y contextos de ejecución locales imposibles de trasladar a través de la red entre dos runtimes heterogéneos (Node.js y el navegador). Las Server Actions no viajan como código fuente, sino como identificadores criptográficos opacos de endpoints RPC. Al invocarse en el cliente, despachan un POST de vuelta al servidor donde reside y se ejecuta la función real.

¿Qué papel desempeña el Client Component Manifest en la compilación de Turbopack?

El manifiesto es un archivo JSON generado en la fase de compilación que relaciona los identificadores lógicos de los componentes de cliente con los archivos reales y hashes en disco. Con él, el servidor sabe con exactitud qué scripts y Resource Hints debe inyectar al cliente cada vez que encuentra una frontera 'use client'.

¿Cómo interactúa la React 19 Taint API con el serializador de Flight Protocol?

Al declarar experimental_taintObjectReference(msg, object), React inscribe dicho objeto en un registro de seguridad en memoria. Si el serializador de Flight tropieza con ese objeto o sus campos protegidos dentro de las props de un Client Component, detiene inmediatamente el proceso arrojando una violación de seguridad, impidiendo que el dato se transmita por la red.

¿Cómo se serializan las promesas pendientes en el protocolo Flight?

El servidor despacha un descriptor de promesa con un ID unívoco (marcador 'P'). El reconciliador de cliente registra una promesa en espera en el árbol. Al completarse la tarea asíncrona en el backend, el servidor emite un chunk adicional con ese mismo ID y los datos resueltos, habilitando al hook use(promise) de React 19 a desbloquear el límite de Suspense.

Inmersión profunda: RSC Protocol y Arquitectura Interna — Next.js 16 App Router

Por qué es necesario#

Para resolver tareas cotidianas en el frontend, suelen bastar las heurísticas superficiales: «los componentes son de servidor por defecto» y para añadir interactividad se requiere 'use client'. Sin embargo, para arquitectos de software y desarrolladores Senior o Lead, dicho conocimiento resulta insuficiente.

Cuando una aplicación escala a cientos de rutas y millones de usuarios concurrentes, surgen interrogantes críticos de bajo nivel:

¿En qué formato físico transmite el servidor el árbol renderizado al cliente, si no es HTML plano ni JSON estándar?
¿Cómo lleva a cabo el navegador la reconciliación (Reconciliation) entre transiciones de página sin recargar el documento y conservando el estado de los componentes de cliente ajenos al cambio?
¿Por qué tipos de datos nativos como Date, BigInt, Map, Set y promesas en streaming atraviesan la red con total fluidez, mientras que funciones y clases emiten errores fatales de serialización?

Comprender en profundidad el React Flight Protocol y la estructura del compilador Turbopack permite concebir sistemas de alto rendimiento con el mínimo overhead e identificar de raíz anomalías arquitectónicas en entornos de producción.

Modelo mental#

El renderizado y entrega de React Server Components no consiste en una mera generación puntual de HTML, sino en una canalización de flujo continuo que comunica dos entornos de ejecución (Node.js/Edge y el navegador).

En el acceso inicial a una web, el servidor entrega el armazón HTML estático (para garantizar un First Contentful Paint, FCP, casi inmediato) en conjunto con el flujo de React Flight Payload.

No obstante, en las navegaciones subsiguientes mediante etiquetas <Link>, el navegador no recarga la página HTML. En su lugar, ejecuta una Soft Navigation (Navegación suave): el navegador emite una petición asíncrona en segundo plano con la cabecera HTTP RSC: 1 (o parámetro ?_rsc=...), recibiendo el flujo de instrucciones Flight sin procesamientos HTML redundantes.

text

CLIENTE (Navegador)                                 SERVIDOR (Node.js/Edge)
   │                                                         │
(1)│── Clic en enlace <Link href="/analytics"> ──────────────►│
   │   GET /analytics?_rsc=123 (Cabecera RSC: 1)             │
   │                                                         │
(2)│                                                         │ 1. Ejecución de Server Components
   │                                                         │ 2. Serialización en Flight Protocol
   │                                                         │    - Resource Hints: H
   │                                                         │    - Client References: I
   │                                                         │    - UI Virtual Tree: J
   │                                                         │
(3)│◄── Flujo RSC Flight Payload (Chunks) ───────────────────┤
   │                                                         │
(4)│ 1. Parseo del flujo Flight                              │
   │ 2. Turbopack descarga los chunks JS necesarios (I)      │
   │ 3. React Reconciler calcula el diferencial en el DOM    │
   │ 4. Actualización de UI ¡SIN recargar la página!         │
   │    (El estado de los Client Components persiste)        │

Ciclo de vida de una petición en el protocolo RSC

1. Ejecución en Server Runtimeserver

El servidor procesa las funciones de los componentes, resuelve consultas a la base de datos y genera el árbol virtual de elementos.

2. Serialización en React Flight Wire Formatflight

El árbol se traduce a un flujo de texto línea a línea. Los nodos de servidor pasan a ser etiquetas JSON y los de cliente se convierten en Client References.

3. Inspección de seguridad con Taint APIsecurity

El runtime de React audita las props enviadas. Si se localiza un objeto marcado como tainted, la serialización se aborta con un error de seguridad.

4. Entrega en streaming de chunksstream

Los fragmentos Flight se transmiten vía HTTP. El navegador inicia el parseo de las primeras líneas antes de concluir el renderizado completo.

5. Reconciliación e Hidratación Selectivaclient

React en el cliente enlaza el nuevo subárbol al DOM en vivo, valida las referencias con el Client Component Manifest e hidrata la interactividad.

PUNTO DE CONTROL #1

Comprobación de concepto: Mecánica de Soft Navigation en App Router

+15 XP

¿Qué solicita el navegador al servidor cuando el usuario pulsa un enlace interno <Link href='/analytics'> en Next.js App Router?

Sintaxis y API: React Flight Protocol#

En el flujo de red, el Flight Payload se estructura como una secuencia de líneas de texto delimitadas por saltos de línea \n. Cada registro comienza con un carácter identificador que tipifica la instrucción:

text

H["/static/css/app.css","stylesheet"]
I["(app-pages-browser)/./components/Counter.tsx",["static/chunks/counter.js"],"Counter"]
J0:["$","div",null,{"className":"container","children":[
  ["$","h1",null,{"children":"Panel de Control"}],
  ["$","$L1",null,{"initialCount":10}]
]}]

H (Resource Hint): Resource Hint para la descarga inmediata en segundo plano de estilos y fuentes.
I (Client Module Import): Registro del Client Component Manifest, indicando la ruta del chunk JavaScript que debe descargar el cliente.
J (JSON Element Tree): Árbol virtual serializado. El símbolo $ denota React.createElement, mientras que $L1 apunta al componente de cliente importado en la línea I.

Depuración interactiva del flujo Flight#

Inspector de Protocolo React Flight (RSC Stream)

Inspeccione el protocolo crudo de serialización de React Server Components

STREAMING EN VIVO

Petición HTTP de navegación suave:

RSC: 1

Solicita Flight stream en lugar de HTML completo

Next-Router-State-Tree

Envía el árbol del cliente para reconciliación

Next-Router-Prefetch: 1

Bandera de precarga enviada por <Link>

Chunks del flujo text/x-component:Haga clic en un chunk

Client Reference (I)Client Reference Manifest (Directiva 'use client')

1:I["./components/MetricCard.tsx",["chunks/metric_card_client.js"],"default"]

Serialized JSX AST (0)Árbol de Elementos Serializado (JSX Stream)

0:{"name":"AnalyticsPage","children":["$","div",null,{"className":"p-6","children":["$","$L1",null,{"metric":"visitors"}]}]}

Lazy Slot Promise ($L1)Resolución de Promesa Asíncrona (Suspense Stream)

2:L1:{"value":14280,"status":"fresh","timestamp":1741859200}

Client Reference (I)

Client Reference Manifest (Directiva 'use client')

El servidor no envía el código fuente de MetricCard, sino un puntero al chunk de bundle que el navegador descarga e hidrata.

Ventaja Arquitectónica:

El restante 90% del código permanece en el servidor sin engordar el bundle JS (Zero-Bundle Size).

Optimización Next.js 16: El parser de Flight Payload en el cliente fue reescrito a un parser nativo en dos fases, acelerando la deserialización un 350%.

Matriz de serialización de React Flight Protocol (Wire Format)

Критерий	Soportado en Flight (Envío seguro)	Prohibido en Flight (Error de serialización)
Tipos primitivos	string, number, boolean, null, undefined, BigInt	Symbol (excepto los registrados mediante Symbol.for)
Estructuras complejas	Plain Objects, Arrays, Map, Set, TypedArrays, ArrayBuffer	Instancias de clases personalizadas (Instancias POO)
Entidades temporales	Date (se mantiene como objeto nativo Date)	RegExp, Funciones generadoras
Tipos asíncronos	Promise (se transmiten en chunks y se resuelven con use())	AsyncGenerator, WebSockets, ReadableStream (directos en props)
Funciones y código	Server Actions (con 'use server', como referencias RPC)	Funciones estándar y manejadores de eventos (onClick)
Elementos de React	JSX Elements (children, slots generados en el servidor)	Objetos React Context, referencias mutables (useRef)

Patrones prácticos#

Patrón 1: Proyección segura de DTO preservando tipos nativos#

React Flight serializa de forma nativa Date y BigInt. ¡Nunca utilices el truco destructivo JSON.parse(JSON.stringify())! Mapea las consultas a través de un DTO explícitamente tipado:

tsxlib/dto/order.ts (DTO Seguro)

export interface OrderDTO {
  id: string;
  totalAmount: bigint;     // ¡Flight serializa BigInt de forma nativa!
  createdAt: Date;         // ¡Flight serializa Date de forma nativa!
  metadata: Map<string, string>; // ¡Flight serializa Map de forma nativa!
}

export function toOrderDTO(raw: {
  id: string;
  total: bigint;
  created_at: Date;
  meta: Record<string, string>;
}): OrderDTO {
  return {
    id: raw.id,
    totalAmount: raw.total,
    createdAt: raw.created_at,
    metadata: new Map(Object.entries(raw.meta)),
  };
}

tsxapp/orders/[id]/page.tsx (Server Component)

import { db } from '@/lib/db';
import { toOrderDTO } from '@/lib/dto/order';
import { ClientOrderView } from './ClientOrderView';

interface PageProps {
  params: Promise<{ id: string }>;
}

export default async function OrderPage({ params }: PageProps) {
  const { id } = await params;
  const rawOrder = await db.order.findUniqueOrThrow({ where: { id } });

  // Transformación a DTO seguro con tipos nativos
  const orderDTO = toOrderDTO(rawOrder);

  // Enviado al cliente: ¡Date, BigInt y Map se conservan sin pérdidas!
  return <ClientOrderView order={orderDTO} />;
}

Patrón 2: Server Actions como descriptores RPC criptográficos#

Cuando una función con la directiva 'use server' se inyecta en un Client Component (por ejemplo, mediante .bind()), el runtime de React encripta los argumentos fijados utilizando Action Closure Encryption:

tsxapp/users/page.tsx (Prop con Server Action Seguro)

import { deleteUserAction } from '@/app/actions/user';
import { DeleteUserButton } from './DeleteUserButton';

export default async function UsersPage() {
  const userId = 'usr_98741';

  // .bind() cifra los argumentos en un token criptográfico dentro del Flight Payload.
  // El cliente solo recibe un descriptor RPC opaco: $F1 = ["$ACTION_ID_123", ["usr_98741"]]
  const boundDelete = deleteUserAction.bind(null, userId);

  return <DeleteUserButton onDelete={boundDelete} />;
}

PUNTO DE CONTROL #2

Comprobación de concepto: Serialización nativa de React Flight frente a JSON

+15 XP

¿Por qué invocar JSON.parse(JSON.stringify(data)) antes de transferir props desde un Server Component a un Client Component se considera un antipatrón en Next.js?

Errores comunes#

Ошибка: Antipatrón JSON.parse(JSON.stringify()): rotura de tipos nativos en Flight

Intentar depurar props antes de entregarlas al cliente mediante JSON.parse(JSON.stringify(data)) acarrea serios efectos colaterales:

Los objetos Date pasan a ser strings ISO 8601, requiriendo un nuevo new Date() en el cliente.
Los valores BigInt arrojan el error fatal TypeError: Do not know how to serialize a BigInt.
Las colecciones Map y Set quedan reducidas a objetos vacíos {}.

¡React Flight soporta de forma nativa Date, BigInt, Map, Set y ArrayBuffer!

Solución: Mapea tus entidades mediante DTOs tipados sin intermediar con JSON.stringify.

Ошибка: Filtración inadvertida de datos y sobrecarga de Flight Payload al usar .bind()

Al vincular parámetros a un Server Action para suministrarlos a un componente de cliente, Next.js cifrará todos los argumentos y los enviará al cliente dentro de la línea W del protocolo Flight. Si cierras sobre un array de 10.000 elementos o una clave privada de API, el Flight Payload se inflará en megabytes y se transmitirán datos sensibles al navegador del usuario.

Solución: Vincula únicamente identificadores escalares mínimos (IDs de entidad). Resuelve claves privadas o datos densos en el servidor dentro de la función Server Action.

tsxPaso seguro de identificadores en Server Actions

// ❌ PELIGROSO: envío de clave secreta en la acción vinculada
// const boundAction = deleteUser.bind(null, userId, secretApiKey);

// ✅ CORRECTO: transferir únicamente el ID público de la entidad
// const boundAction = deleteUser.bind(null, userId);

Ошибка: Fallo de navegación en despliegues con cambio de versión (Version Skew)

Un usuario mantiene la página abierta en la versión v1. Publicas la versión v2, donde los hashes de los chunks de JavaScript han cambiado. El usuario pulsa un enlace:

El navegador solicita ?_rsc=... y recibe el Flight Payload de la v2.
El Flight Payload contiene una línea I con el hash chunk-v2-abc.js.
El navegador intenta descargar ese chunk, pero la CDN o la caché devuelven 404.

Cómo lo solventa Next.js internamente: Next.js intercepta la discrepancia de versiones y dispara automáticamente una Hard Navigation (recarga completa del documento), actualizando de forma transparente la sesión del usuario a la versión v2.

Ошибка: Mutar props en el cliente corrompe las navegaciones subsiguientes

Los objetos deserializados a partir del Flight Payload son congelados por React mediante Object.freeze. Alterar directamente una propiedad como props.user.name = 'Nuevo' arrojará una excepción en modo estricto o generará desincronizaciones en el reconciliador en visitas futuras.

Preguntas de entrevista#

Preguntas de entrevista8 preguntas

Temas relacionados

Componentes Server y Client en Next.js: Arquitectura de dos mundos Patrones de composición de componentes y el Donut Pattern Streaming SSR y arquitectura de Suspense Partial Prerendering (PPR): prerenderizado híbrido

Inmersión profunda: RSC Protocol y Arquitectura Interna

Por qué es necesario#

Modelo mental#

1. Arquitectura de navegación suave (Soft Navigation)#

Sintaxis y API: React Flight Protocol#

Depuración interactiva del flujo Flight#

Inspector de Protocolo React Flight (RSC Stream)

Client Reference Manifest (Directiva 'use client')

Patrones prácticos#

Patrón 1: Proyección segura de DTO preservando tipos nativos#

Patrón 2: Server Actions como descriptores RPC criptográficos#

Errores comunes#

Ошибка: Antipatrón JSON.parse(JSON.stringify()): rotura de tipos nativos en Flight

Ошибка: Filtración inadvertida de datos y sobrecarga de Flight Payload al usar .bind()

Ошибка: Fallo de navegación en despliegues con cambio de versión (Version Skew)

Ошибка: Mutar props en el cliente corrompe las navegaciones subsiguientes

Preguntas de entrevista#

Por qué es necesario#

Modelo mental#

1. Arquitectura de navegación suave (Soft Navigation)#

Sintaxis y API: React Flight Protocol#

Depuración interactiva del flujo Flight#

Inspector de Protocolo React Flight (RSC Stream)

Client Reference Manifest (Directiva 'use client')

Patrones prácticos#

Patrón 1: Proyección segura de DTO preservando tipos nativos#

Patrón 2: Server Actions como descriptores RPC criptográficos#

Errores comunes#

Ошибка: Antipatrón JSON.parse(JSON.stringify()): rotura de tipos nativos en Flight

Ошибка: Filtración inadvertida de datos y sobrecarga de Flight Payload al usar .bind()

Ошибка: Fallo de navegación en despliegues con cambio de versión (Version Skew)

Ошибка: Mutar props en el cliente corrompe las navegaciones subsiguientes

Preguntas de entrevista#