Next.js
Explica las fases de una aplicación Next.js desde desarrollo y build hasta request, render de servidor, streaming, hidratación y navegación cliente.
Una aplicación Next.js no se ejecuta una sola vez ni en un único entorno. Parte del trabajo ocurre durante el build, otra parte cuando llega una petición, otra durante el render de React en servidor y otra después de que el navegador recibe e hidrata la interfaz. Separar estas fases es imprescindible para comprender datos, caché, variables de entorno y errores.
Cuando escribes un componente dentro de app, su código puede participar en varios momentos:
desarrollo
↓
build
↓
prerendering opcional
↓
request o navegación
↓
render de servidor
↓
stream de respuesta
↓
hidratación cliente
↓
interacciones y futuras navegacionesNo todo componente atraviesa todas las fases. Una página completamente estática puede quedar preparada durante el build. Una ruta que lee cookies se resuelve en cada request. Un Client Component puede generar HTML inicial en servidor y después hidratarse en navegador. Un Route Handler puede devolver JSON sin renderizar una página.
El error mental frecuente consiste en reducir todo a “servidor” y “cliente”. Next.js también distingue cuándo se ejecuta y qué artefacto produce cada paso.
Sin separar fases, aparecen afirmaciones engañosas:
use client, por lo tanto solo se renderiza en el navegador”. También puede participar en el HTML inicial.router.refresh(), por lo tanto limpié toda la caché”. Refresh solicita una nueva representación, pero no invalida automáticamente todas las capas.window, entonces nunca llega al cliente”. Si pertenece al grafo importado por una boundary cliente, puede terminar en el bundle.El modelo por fases permite localizar una decisión en el momento correcto.
source code
│
├── next dev
│ └─ compilación incremental + servidor de desarrollo
│
└── next build
├─ análisis de rutas
├─ compilación servidor
├─ bundles cliente
├─ assets estáticos
├─ prerendering cuando aplica
└─ manifest y output de despliegue
↓
runtime de producción
↓ request
Proxy / router / caches
↓
Server Components y handlers
↓
HTML + RSC payload + assets
↓
navegador
↓
hydration + navigation runtimeNext.js coordina la construcción del output, pero la plataforma determina cómo se sirven procesos, funciones, CDN, caché y regiones.
next dev inicia un entorno orientado a feedback rápido:
pnpm devDurante desarrollo suelen intervenir:
Este entorno no representa con precisión el rendimiento ni todas las decisiones del build de producción.
Permite iterar rápidamente y detectar errores.
No confirma que:
Por eso la validación real incluye next build.
pnpm buildEl build transforma el proyecto en un output ejecutable. Entre otras tareas, Next.js:
const value = process.env.FEATURE_MODE;Dependiendo de dónde se use, el valor puede incorporarse al output durante build o leerse desde el runtime servidor. Las variables expuestas mediante prefijos públicos terminan en código cliente y deben considerarse públicas.
Funciones de prerendering pueden consultar datos:
export async function generateStaticParams() {
const products = await listPublishedProducts();
return products.map((product) => ({ slug: product.slug }));
}El resultado describe parámetros conocidos para generación. No significa que la función vuelva a ejecutarse en cada visita.
Prerendering produce contenido antes de una petición concreta. Puede ocurrir durante build o mediante mecanismos de regeneración.
componentes + datos disponibles
↓
HTML y RSC payload
↓
cache / archivos de salidaUna ruta prerenderizada puede servirse rápidamente desde almacenamiento o CDN.
La decisión depende de las APIs y configuración actuales. Leer información específica de la petición, como cookies o headers, suele requerir request time. Las reglas exactas han cambiado entre versiones; no memorices una lista antigua sin revisar la documentación actual.
Una ruta estática puede regenerarse mediante revalidation. “Estático” describe cuándo se generó la respuesta, no que nunca pueda actualizarse.
Una solicitud puede atravesar varias capas:
browser
↓
CDN / proxy de plataforma
↓
Next.js Proxy, redirects y rewrites
↓
router
↓
cache hit o ejecuciónSegún la URL y método, el destino puede ser:
No toda petición ejecuta React. Un archivo en public puede servirse directamente; un endpoint puede devolver JSON; una respuesta prerenderizada puede salir de caché.
Cuando una ruta necesita ejecución, Next.js renderiza el árbol correspondiente.
segmentos coincidentes
↓
layouts + pages
↓
Server Components
↓
Client Component references
↓
HTML + RSC payloadSe ejecutan en el entorno servidor y pueden acceder a recursos privados:
export default async function OrdersPage() {
const orders = await db.order.findMany();
return <OrdersTable orders={orders} />;
}No envían su implementación como JavaScript cliente.
Una Client Component define una frontera de módulos que necesita capacidades cliente:
"use client";
export function Counter() {
const [count, setCount] = useState(0);
return <button onClick={() => setCount((value) => value + 1)}>{count}</button>;
}Puede participar en el HTML de la respuesta, pero su código también debe descargarse para hidratarse.
El servidor puede producir varios artefactos relacionados:
No confundas el RSC payload con JSON de negocio ni con HTML.
Suspense permite dividir la respuesta:
export default function DashboardPage() {
return (
<main>
<DashboardHeader />
<Suspense fallback={<OrdersSkeleton />}>
<RecentOrders />
</Suspense>
</main>
);
}El servidor puede enviar primero una shell útil y completar regiones cuando estén listas:
shell + fallback
↓
primer fragmento visible
↓
contenido de RecentOrders
↓
respuesta completadaStreaming mejora el tiempo de aparición de contenido, pero no elimina latencia ni garantiza interactividad inmediata.
El navegador analiza el HTML y puede mostrarlo antes de descargar todo el JavaScript.
Después:
HTML visible
≠
JavaScript descargado
≠
hidratación completaEsta diferencia explica por qué una página puede verse pero todavía no responder a una interacción.
Cuando el usuario utiliza <Link>, Next.js puede evitar una recarga completa:
click en Link
↓
router cliente
↓
RSC request / datos prefetched
↓
React reconcilia nuevo árbol
↓
layouts compatibles se preservanLa navegación puede reutilizar segmentos y estado cliente existente. Una carga directa de la misma URL comienza desde un documento nuevo y no tiene el historial de slots o rutas interceptadas de la navegación anterior.
Por eso debes probar ambos escenarios:
Una mutación puede modificar la fuente de datos sin actualizar automáticamente todas las representaciones cacheadas:
Server Action
↓
actualiza base de datos
↓
revalidatePath / revalidateTag / updateTag
↓
router obtiene representación nuevaLa API correcta depende del nivel de consistencia requerido. Invalidar demasiado crea trabajo; invalidar muy poco deja contenido obsoleto.
Supón una página /products y una Action de edición.
// app/products/page.tsx
export default async function ProductsPage() {
const products = await listProducts();
return <ProductList products={products} />;
}// features/products/actions.ts
"use server";
import { revalidatePath } from "next/cache";
export async function updateProduct(formData: FormData) {
const input = parseProductForm(formData);
await productRepository.update(input);
revalidatePath("/products");
}listProducts, la página puede prerenderizarse o ejecutarse bajo otra estrategia.revalidatePath marca la representación relacionada para actualización.La llamada de revalidación no sustituye una transacción de base de datos ni autorización.
Puede usar credenciales y conexiones privadas si no cruza una boundary cliente.
Todo lo incluido en el bundle puede inspeccionarse. Incluso una variable de entorno llamada “secret” deja de ser secreta si se expone al cliente.
Un dato calculado en servidor puede filtrarse si se pasa como prop a un Client Component o se incluye en una respuesta. El hecho de que el código fuente permanezca en servidor no protege los datos enviados.
Next.js puede ejecutar código bajo distintos entornos según capacidades y plataforma:
Aporta APIs y paquetes del ecosistema Node. Es la opción general para acceso a bases de datos, filesystem permitido por la plataforma y librerías de servidor.
Tienen restricciones y APIs distintas. No asumas compatibilidad con cualquier paquete Node.
Tiene DOM, storage y APIs web del usuario, pero no credenciales privadas del servidor.
Antes de elegir runtime, revisa dependencias, latencia, límites de ejecución y soporte de plataforma.
Una llamada de envío de correo dentro de código ejecutado al prerenderizar podría repetirse al construir. El build debe producir artefactos, no realizar acciones de negocio irreversibles.
No existe una petición de usuario concreta en build time.
window, document y localStorage no existen en servidor.
En realidad lo envía al cliente.
Los errores de rutas, serialización y output pueden aparecer únicamente en next build o next start.
Son capas relacionadas pero distintas. Una navegación nueva no garantiza que la fuente remota se vuelva a consultar.
Pregunta en este orden:
next dev, next build o next start?Este orden evita corregir un problema de build con un Effect cliente o un problema de caché reiniciando state local.
<Link>?Crear y configurar un proyecto Next.js conecta estas fases con scripts, estructura, versiones, variables y configuración reproducible.