Enrutamiento basado en archivos en Next.js App Router

Contexto arquitectónico y motivación#

El enrutamiento constituye la columna vertebral de una aplicación web, definiendo cómo se mapean las URLs al código, datos y árbol de componentes en tiempo de ejecución. En las SPAs tradicionales de cliente (basadas en react-router), la navegación depende de objetos centralizados de configuración o árboles declarativos de componentes. A escala empresarial, este enfoque introduce graves cuellos de botella:

• Conflictos de fusión por centralización: Un único archivo de rutas se convierte en un foco continuo de conflictos git en equipos distribuidos.
• Sobrecarga de Code Splitting manual: La división de código (Code Splitting) requiere mantenimiento manual constante con importaciones dinámicas (React.lazy), donde cualquier descuido filtra dependencias pesadas en el bundle inicial.
• Fuga de lógica de servidor al cliente: El enrutador de cliente debe descargar código que podría ejecutarse exclusivamente en el servidor (consultas directas a bases de datos, parsers de Markdown, tokens confidenciales).
• Pérdida de estado en transiciones: Resulta complejo preservar de forma granular el estado de las estructuras padre sin provocar re-renderizados innecesarios en todo el árbol de componentes.

Next.js App Router redefine este paradigma mediante el enrutamiento basado en archivos (file-based routing). La estructura del sistema de archivos dentro de la carpeta app se compila directamente por el empaquetador Turbopack en el grafo de rutas de la aplicación. Esto elimina registros manuales, aísla páginas, automatiza el code splitting a nivel de segmento y garantiza un tamaño de bundle de cliente cero (Zero-Bundle Size) para los Server Components por defecto.

Modelo mental: análisis topológico de segmentos#

En el modelo de App Router, la unidad estructural elemental es el segmento de ruta (Route Segment). Cada carpeta anidada dentro de app representa un segmento URL independiente.

Por ejemplo, la carpeta app/dashboard/settings corresponde con exactitud a la URL /dashboard/settings. Sin embargo, crear carpetas no expone automáticamente rutas públicas. Un segmento se convierte en un endpoint navegable solo cuando contiene un archivo hoja especial: page.tsx. Si page.tsx no existe, la carpeta permanece como una rama organizativa interna, utilizada exclusivamente para agrupar rutas o compartir layouts comunes.

Cada segmento está aislado y garantiza la preservación de estado (Preserved State): los layouts padre no se desmontan ni re-renderizan al cambiar de página hija, y las actualizaciones se transmiten como un flujo diferencial de React Server Components.

3. Algoritmo de ejecución y ciclo de vida (Runtime Execution)#

El ciclo de resolución de una ruta —desde la interacción del usuario hasta la reconciliación final en el DOM del navegador— sigue una secuencia estricta gestionada por Turbopack y el motor de streaming de React 19:

4. Convenciones del sistema de archivos y contratos de API#

Next.js asigna responsabilidades sistémicas específicas a archivos con nombres reservados. Turbopack compila estos archivos en una jerarquía estricta de componentes de React.

Desglose progresivo del sistema de archivos#

Nivel 1: Pareja esencial de Layout y Página

• page.tsx — El único punto de entrada que genera una URL pública. Sin este archivo, la carpeta no produce una ruta accesible.
• layout.tsx — La estructura base de un segmento. Debe recibir la prop { children: React.ReactNode }. app/layout.tsx (Root Layout) es obligatorio en todo el proyecto y es el único lugar donde se declaran las etiquetas <html> y <body>.

Nivel 2: Componentes de límites y estados

• loading.tsx — Límite declarativo de <Suspense>, que entrega inmediatamente un skeleton durante la carga en servidor.
• error.tsx — Capturador aislado de errores en cliente (<ErrorBoundary>). Debe incluir obligatoriamente la directiva 'use client'. Si una página hija falla, el layout padre y la navegación permanecen plenamente operativos.
• not-found.tsx — Interfaz 404 del segmento, activada programáticamente con notFound().

Nivel 3: Convenciones organizativas

• (folder) — Route Group (Grupo de rutas): organiza funcionalidades o aísla layouts sin modificar la estructura URL. Por ejemplo, app/(marketing)/about/page.tsx responde en la ruta limpia /about.
• _folder — Private Folder (Carpeta privada): queda excluida del sistema de rutas.

app/
├── layout.tsx             # Root Layout (<html> y <body>)
├── page.tsx               # Página de inicio (/)
├── not-found.tsx          # 404 global
├── global-error.tsx       # Límite raíz de errores fatales
├── (marketing)/           # Route Group (no altera la URL)
│   ├── about/
│   │   └── page.tsx       # Ruta: /about
│   └── pricing/
│       └── page.tsx       # Ruta: /pricing
└── dashboard/
    ├── layout.tsx         # Layout anidado con sidebar persistente
    ├── loading.tsx        # Suspense fallback para dashboard
    ├── error.tsx          # Client Error Boundary ('use client')
    ├── not-found.tsx      # 404 de segmento
    ├── page.tsx           # Ruta: /dashboard
    ├── _components/       # Carpeta privada (fuera de enrutamiento)
    │   └── MetricCard.tsx
    └── settings/
        └── page.tsx       # Ruta: /dashboard/settings

5. Parámetros asíncronos e integración con React 19#

A partir de Next.js 15 y los estándares de React 19, los parámetros de ruta params y los parámetros de búsqueda searchParams se entregan a las páginas, layouts y funciones generateMetadata como Promesas asíncronas (Promise).

¿Por qué los parámetros se convirtieron en Promises?#

En el modelo síncrono (Next.js 13–14), el servidor debía retrasar la generación de la página hasta parsear completamente la petición HTTP entrante (incluyendo cabeceras y cookies). Esto bloqueaba artificialmente el tiempo hasta el primer byte (TTFB).

La transición a Promise es la base arquitectónica de Partial Prerendering (PPR):

1. La estructura estática de la página (cabecera, navegación, marco visual) se precompila en HTML durante el build y se sirve desde una CDN en menos de 50 ms.
2. Los parámetros de ruta y búsqueda llegan al componente de página como promesas pendientes de resolución.
3. Si la lectura de await params está envuelta en un límite <Suspense> de React, la parte estática no espera. En cuanto el runtime resuelve la petición, el servidor envía los fragmentos dinámicos a través de la conexión HTTP abierta.

import { Metadata } from 'next';
import { notFound } from 'next/navigation';

interface AnalyticsPageProps {
  params: Promise<{ period: string }>;
  searchParams: Promise<{ metric?: string }>;
}

// 1. Generación dinámica de metadatos
export async function generateMetadata(props: AnalyticsPageProps): Promise<Metadata> {
  const { period } = await props.params;
  return {
    title: `Informe de periodo: ${period.toUpperCase()}`,
    description: `Telemetría agregada para el periodo ${period}`,
  };
}

// 2. Página de servidor con parámetros asíncronos
export default async function AnalyticsPage(props: AnalyticsPageProps) {
  // Resolución asíncrona de parámetros en Next.js 15+
  const params = await props.params;
  const searchParams = await props.searchParams;

  const validPeriods = ['day', 'week', 'month'];
  if (!validPeriods.includes(params.period)) {
    notFound();
  }

  const activeMetric = searchParams.metric ?? 'all';

  return (
    <main className="p-6 space-y-4">
      <h1 className="text-2xl font-bold">Periodo: {params.period}</h1>
      <p className="text-text-muted">Filtro métrico activo: {activeMetric}</p>
    </main>
  );
}

Lectura de parámetros asíncronos en Client Components mediante React 19 use()#

Cuando se envía una Promesa de parámetros a un Client Component, se desenrolla síncronamente durante el renderizado con la primitiva nativa de React 19 —el hook use():

'use client';

import { use } from 'react';

interface ClientSectionViewProps {
  paramsPromise: Promise<{ section: string }>;
}

export function ClientSectionView({ paramsPromise }: ClientSectionViewProps) {
  // Desenvolvimiento de la promesa de parámetros durante el renderizado del cliente
  const { section } = use(paramsPromise);

  return (
    <div className="p-4 rounded-lg bg-bg-surface border border-border">
      <span className="text-xs text-text-muted uppercase">Segmento de cliente:</span>
      <h3 className="text-lg font-mono font-bold text-accent-cyan">{section}</h3>
    </div>
  );
}

6. Protocolos bajo el capó: React Flight y Client Router Cache#

Durante una navegación suave en cliente (<Link href="...">), el navegador no solicita un nuevo documento HTML. En su lugar, el enrutador envía una petición HTTP en segundo plano con encabezados de control:

• RSC: 1 — Indica al servidor que retorne un flujo serializado del grafo de componentes en lugar de HTML plano.
• Next-Router-State-Tree — Envía una instantánea codificada del árbol de segmentos montado en el navegador. El servidor calcula el Ancestro Común Más Bajo (LCA) y ejecuta exclusivamente los componentes que han cambiado.

Evolución de Client Router Cache y staleTimes en Next.js 15+#

En Next.js 15, la caché en memoria del navegador (Client Router Cache) se rediseñó para solventar problemas de datos desactualizados:

1. Segmentos dinámicos: El tiempo de validez (staleTime) es de 0 segundos. Cada transición a una página dinámica solicita un Flight Payload fresco al servidor.
2. Segmentos estáticos y precarga: Para rutas estáticas (SSG) y enlaces precargados, la frescura se mantiene durante 5 minutos (300 segundos).
3. Límites loading.tsx: Los esqueletos de streaming se almacenan en caché durante 5 minutos, evitando parpadeos de spinners en visitas sucesivas.
4. Layouts compartidos: Nunca se vuelven a solicitar por red al navegar entre páginas hermanas bajo el mismo layout padre.

La configuración de retención de caché se define en next.config.ts:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30, // Mantener rutas dinámicas en memoria durante 30 segundos
      static: 180,  // Mantener segmentos estáticos durante 3 minutos
    },
  },
};

export default nextConfig;

Semántica de prefetch en App Router#

• prefetch={null} (por defecto): Descarga el Flight Payload completo para rutas estáticas. En rutas dinámicas, descarga únicamente el esqueleto hasta el loading.tsx más próximo.
• prefetch={true}: Fuerza la precarga del árbol completo, incluyendo datos dinámicos.
• prefetch={false}: Deshabilita por completo la precarga al entrar en el viewport y al pasar el cursor (hover). Los desarrolladores pueden ejecutar router.prefetch() de forma manual.

7. Patrones de producción y arquitectura#

Patrón 1: Colocalización segura de funcionalidades#

Ubicar componentes, server actions y tipos directamente junto a la ruta previene el desorden en carpetas globales y protege los archivos privados de exponerse por error como endpoints públicos.

interface Invoice {
  id: string;
  amount: number;
  status: 'paid' | 'pending';
}

interface InvoiceListProps {
  items: Invoice[];
}

export function InvoiceList({ items }: InvoiceListProps) {
  return (
    <ul className="divide-y divide-border border border-border rounded-lg bg-bg-surface">
      {items.map((invoice) => (
        <li key={invoice.id} className="p-3 flex justify-between items-center text-sm">
          <span className="font-mono text-accent-cyan">#{invoice.id}</span>
          <span className="font-semibold">${(invoice.amount / 100).toFixed(2)}</span>
        </li>
      ))}
    </ul>
  );
}

import { InvoiceList } from './_components/InvoiceList';

async function getInvoices() {
  return [
    { id: 'inv-101', amount: 4900, status: 'paid' as const },
    { id: 'inv-102', amount: 12000, status: 'pending' as const },
  ];
}

export default async function BillingPage() {
  const invoices = await getInvoices();

  return (
    <section className="space-y-4">
      <h2 className="text-xl font-bold">Gestión de Facturación</h2>
      <InvoiceList items={invoices} />
    </section>
  );
}

Patrón 2: Configuración declarativa de segmento (Segment Config)#

En page.tsx y layout.tsx, define de forma declarativa las estrategias de ejecución y caché para el subárbol:

// Forzar renderizado dinámico en cada petición entrante
export const dynamic = 'force-dynamic';

// Aislar el entorno de ejecución (Runtime Node.js)
export const runtime = 'nodejs';

// Tiempo de vida de la caché del segmento en segundos (Incremental Static Regeneration, ISR)
export const revalidate = 300;

export default async function ReportsPage() {
  return <div className="p-6">Informes ejecutivos (actualizados cada 5 minutos)</div>;
}

8. Casos límite, fallos del sistema y seguridad#

9. Preguntas técnicas de entrevistas para ingenieros Senior/Staff#