Next.js
Request lifecycle en Next.js
Recorre una solicitud desde CDN, configuración y Proxy hasta routing, caché, Route Handler, render React, streaming e hidratación del navegador.
- Última actualización
- Actualizada
- Nivel
- Fundamentos
Next.js
Recorre una solicitud desde CDN, configuración y Proxy hasta routing, caché, Route Handler, render React, streaming e hidratación del navegador.
Una request de Next.js puede resolverse desde CDN, archivos estáticos, Proxy, caché, Route Handler o render de React. Una navegación cliente puede solicitar un RSC payload en lugar de un documento. Comprender el lifecycle permite localizar redirects, headers, autenticación, status y latencia en la fase correcta.
Flujo conceptual:
client request
↓
platform/CDN
↓
next.config headers and redirects
↓
Proxy
↓
rewrites and filesystem routing
↓
cache hit or runtime execution
↓
Route Handler OR React render OR asset
↓
stream/response
↓
browser parse, hydrate or reconcileNo toda request atraviesa todas las fases. Un asset puede terminar en CDN; una route cacheada puede no ejecutar la page; un webhook termina en Route Handler sin React.
Abrir URL, refresh o navegación entre root layouts:
Accept: text/html
→ HTML document + scripts + RSC data<Link>/router:
RSC request
→ segment payload
→ React merges treePreserva layouts/state compatibles.
POST al contexto de la route donde se usa la Action. No es un endpoint separado visible en el árbol como Route Handler.
Request HTTP directa a route.ts.
Puede resolverse por filesystem/CDN/optimizador.
Distinguirlas importa para Proxy matchers, logs y caché.
Antes de Next.js puede existir:
Un cache hit puede evitar que tu proceso reciba la request. Los headers y logs de la plataforma ayudan a comprobarlo.
Orden simplificado documentado:
1 next.config headers
2 next.config redirects
3 Proxy
4 beforeFiles rewrites
5 filesystem routes
6 afterFiles rewrites
7 dynamic routes
8 fallback rewritesEsto explica por qué una rewrite o redirect puede impedir que una page se ejecute.
async headers() {
return [{
source: "/:path*",
headers: [{ key: "X-Content-Type-Options", value: "nosniff" }],
}];
}Son reglas conocidas en build/configuración. Para valores por request necesitas Proxy o respuesta runtime.
No agregues headers sensibles a assets o endpoints sin revisar scope.
async redirects() {
return [{ source: "/old", destination: "/new", permanent: true }];
}Ocurren antes de Proxy. Una regla aquí puede evitar lógica posterior.
Para decisiones de sesión, usa servidor/Proxy según necesidad, no una lista estática.
Ejecuta antes de resolver rutas y puede:
Debe ser rápido y con matcher preciso. No es el lugar de consultas pesadas ni autorización definitiva.
Una rewrite cambia el destino interno sin cambiar la URL visible:
/public-path
→ rewrite /internal/path
→ browser keeps /public-pathAporta migraciones, multi-tenancy o proxy hacia backend. Riesgos:
Next.js busca assets y rutas estáticas/dinámicas. page.tsx y route.ts compiten en el mismo segmento final, por eso no pueden coexistir allí.
Una route group no aparece en pathname. Proxy y rewrites trabajan con URL, no con nombres internos de groups.
Antes de ejecutar todo el árbol, Next.js/plataforma puede reutilizar:
fetch/data cache del modelo previo.Un hit reduce trabajo. Un miss ejecuta fill/render.
Para diagnosticar, registra cache status y no asumas que “la page corrió”.
match route.ts
→ parse request
→ authenticate
→ validate/authorize
→ service
→ Response/streamNo genera HTML React salvo que tú produzcas contenido manualmente. Status y headers permanecen bajo el Handler.
match layouts/pages
→ resolve params/request APIs
→ execute server tree
→ Suspense boundaries
→ HTML/RSC stream
→ client hydration/navigation mergeDynamic APIs pueden diferir regiones al request. Cache Components puede servir shell y ejecutar contenido bajo Suspense.
Cuando comienza la respuesta:
headers committed
→ shell bytes
→ later segmentsDespués no puedes cambiar status fácilmente. Determina redirects/not-found críticos antes de iniciar stream cuando el status importa.
Un error posterior puede activar fallback cliente o boundary sin cambiar 200 ya enviado.
Lectura:
const store = await cookies();
const session = store.get("session");Es request context y hace dinámica esa región.
Escritura debe ocurrir antes de que streaming impida modificar headers, normalmente en Server Action, Route Handler o Proxy:
store.set("session", token, options);No intentes establecer cookie desde un Server Component durante render general.
Proxy puede clonar headers y añadir contexto:
const requestHeaders = new Headers(request.headers);
requestHeaders.set("x-request-id", requestId);
return NextResponse.next({ request: { headers: requestHeaders } });No confíes en un header del cliente con el mismo nombre. Sobrescríbelo en una frontera controlada.
Evita headers grandes; pueden producir 431.
request ID
→ Proxy
→ Server Component/Handler
→ DB query
→ external service
→ logs/error responseAcepta un ID upstream solo si la infraestructura lo controla; de lo contrario genera uno.
No incluyas PII.
Filtro rápido para redirigir usuarios sin cookie aparente.
Valida sesión y permiso real.
Oculta o muestra controles.
Proxy check
≠ session validation
≠ resource authorizationUna Action puede quedar fuera del matcher si cambia la route donde se usa. Siempre autoriza dentro.
Flujo:
Link intent
→ prefetch maybe
→ RSC request
→ server render/cache
→ payload
→ reconciliation
→ focus/scrollNo hay necesariamente window.load. Analytics debe escuchar navegación mediante hooks o instrumentation apropiada.
El router puede reutilizar una respuesta prefetcheada; una invalidación servidor debe coordinar freshness.
browser document request
→ new HTML
→ all client state resetsPrueba rutas interceptadas y slots directamente. Soft navigation puede esconder la ausencia de default.tsx.
502/timeout antes de app.
Redirect loop o respuesta temprana.
error boundary/digest.
Partial response.
Mismatch/warning.
Event/Action failure.
El mismo síntoma visual puede tener causas diferentes; usa logs correlacionados.
Mide:
No atribuyas todo TTFB alto a React.
GET /dashboard
→ CDN miss
→ headers/redirect rules
→ Proxy checks session cookie shape
→ route match
→ cached shell
→ Suspense user session + dashboard query
→ stream
→ hydrate filtersLa Action de editar no confía en el Proxy; vuelve a validar sesión/tenant y actualiza tags.
Proxy dispone de waitUntil bajo su evento para trabajo que continúa después de respuesta, como logging. No lo uses para procesos críticos sin un sistema durable; la plataforma puede terminar ejecución.
Route Handlers también deberían encolar jobs largos.
next.config.Proxy: reemplazo actual de Middleware profundiza en la frontera previa al routing, matchers, rewrites y límites.