Mejores prácticas de enrutamiento en Next.js

Un resumen condensado de las 25 mejores prácticas más importantes extraídas de cada página en esta sección.

Espera params y searchParams: En Next.js 15+ ambas props son Promises en Server Components — const { id } = await params — la desestructuración sin await devuelve el objeto Promise y tus búsquedas silenciosamente devuelven undefined.
No dejes que page.tsx colisione con route.tsx: Una carpeta no puede contener tanto page.tsx como route.tsx — el Route Handler sombreará la página, así que mantén las rutas API bajo app/api/ para evitar conflictos silenciosos.
Usa template.tsx para reiniciar por cada navegación: layout.tsx persiste a través de la navegación y su estado sobrevive a los cambios de ruta hija; cuando específicamente necesitas remontar (p. ej., reiniciar animaciones o estado en cada navegación), usa template.tsx en su lugar.
Analiza los tipos de parámetros dinámicos: Todo valor de segmento dinámico llega como una cadena — const postId = Number(params.id) — así que convierte a la forma que realmente necesitas en lugar de confiar solo en la anotación de tipo.
Usa [[...slug]] cuando la ruta base debe coincidir: Un catch-all [...path] no coincide con la ruta padre, así que /docs es 404; cambia a [[...path]] o añade un page.tsx separado junto a él cuando el segmento base debe resolver.
Deja que lo estático gane sobre lo dinámico explícitamente: Cuando las rutas estáticas y dinámicas se superponen, la estática siempre gana, así que puedes mantener un /blog/about/page.tsx junto a [slug]/page.tsx sin conflicto.
generateStaticParams se ejecuta en tiempo de compilación: La función se ejecuta durante next build, así que cualquier fuente de datos no disponible falla la compilación; combínala con dynamicParams = true cuando las nuevas rutas aún deben renderizarse en la primera solicitud.
error.tsx debe ser "use client": React Error Boundaries requieren ciclo de vida del cliente, así que cada error.tsx necesita la directiva "use client" — y solo captura errores debajo de sí, nunca en el layout.tsx hermano del mismo segmento.
global-error.tsx controla html y body: global-error.tsx reemplaza el layout raíz completo cuando se activa, así que debe renderizar su propio <html><body>; también ten en cuenta que solo se activa en producción (la superposición de desarrollo se ejecuta en desarrollo).
notFound y redirect lanzan excepciones: Ambos lanzan errores centinela de Next.js, así que un try/catch circundante los traga — llámalos fuera de try/catch, o usa unstable_rethrow en el bloque catch para dejarlos propagarse.
Reserva root not-found para rutas no coincidentes: El root not-found.tsx captura automáticamente cualquier URL que no coincida con una ruta, mientras que los archivos not-found.tsx anidados solo se activan cuando explícitamente llamas a notFound() desde dentro de ese subárbol.
Los layouts no pueden leer searchParams: Solo las pages reciben searchParams; si un layout necesita estado de URL, levanta la lógica a una page o un Client Component que usa useSearchParams() dentro de un límite Suspense.
Pasa datos vía Context, no props de layout: Los layouts no pueden reenviar props a sus hijos, así que comparte estado a través de un proveedor Client Context, cookies, o un auxiliar Server Component que vuelve a obtener en cada hijo.
Importa useRouter desde next/navigation: En el App Router, useRouter, usePathname, y useSearchParams viven en next/navigation; next/router es el Pages Router y silenciosamente falla o es 404 cuando se importa.
Envuelve useSearchParams en Suspense: useSearchParams() sin un límite <Suspense> circundante opta toda la ruta al renderizado del lado del cliente — siempre delimítalo: <Suspense fallback={null}><SearchFilters /></Suspense>.
Usa useTransition para UI pendiente: router.push() devuelve void, así que envuelve navegaciones en useTransition — startTransition(() => router.push("/dashboard")) — para obtener una bandera isPending y deshabilitar botones o mostrar spinners durante cambios de ruta.
router.refresh con alcance a la ruta actual: refresh() vuelve a obtener datos del servidor para la ruta activa solo; otras rutas cacheadas permanecen obsoletas, así que combínala con revalidateTag/revalidatePath cuando la mutación afecta hermanos.
Controla Link prefetch y scroll: <Link> prefetcha en la entrada del viewport y se desplaza hacia arriba por defecto — <Link href="/settings" prefetch={false} scroll={false}> — establece prefetch={false} en enlaces raramente usados y scroll={false} para UIs de pestaña/filtro que deben permanecer en su lugar.
Siempre establece un matcher de middleware: Sin config.matcher tu middleware se ejecuta en cada solicitud incluyendo /_next/static y favicons — export const config = { matcher: ["/dashboard/:path*", "/api/:path*"] } — define el alcance explícitamente y excluye destinos de redirección para evitar bucles infinitos.
Edge middleware prohíbe APIs Node: Middleware se ejecuta en Edge Runtime, así que bcrypt, fs, y la mayoría de drivers de base de datos se rompen en compilación o runtime — usa solo APIs Web y librerías compatibles con edge.
Devuelve NextResponse.next para continuar: NextResponse.next() no hace corto-circuito; debes return (o una redirección/reescritura) para realmente detener la cadena de middleware, de lo contrario la lógica subsecuente sigue ejecutándose.
Cada slot paralelo necesita default.tsx: Las carpetas @slot deben incluir un fallback default.tsx, de lo contrario navegaciones duras o subrutas no coincidentes son 404; los slots también deben ser hijos directos del layout y no pueden anidar dentro uno del otro.
Reserva espacio para slots independientes: Los slots de ruta paralela se resuelven independientemente, así que da a cada uno una altura fija o skeleton que coincida con el contenido final — de lo contrario streaming causa desplazamiento de layout visible mientras cada slot se rellena.
Ten en mente la convención del punto de intercepción: (.), (..), (..)(..), y (...) cuentan los segmentos de grupos de ruta igual que las carpetas regulares, así que los grupos de ruta pueden requerir un salto (..) extra; la falta de default.tsx en el slot anfitrión también rompe el cierre de back-navigation.
Los grupos de ruta no pueden colisionar: Dos carpetas (group) no pueden resolver a la misma ruta de URL (la compilación falla), y múltiples layouts raíz fuerzan una recarga de página completa entre grupos en lugar de navegación suave — mantén la ruta del inicio / en exactamente un grupo.

Un resumen condensado de las 25 mejores prácticas más importantes extraídas de cada página en esta sección.

Espera params y searchParams: En Next.js 15+ ambas props son Promises en Server Components — const { id } = await params — la desestructuración sin await devuelve el objeto Promise y tus búsquedas silenciosamente devuelven undefined.

No dejes que page.tsx colisione con route.tsx: Una carpeta no puede contener tanto page.tsx como route.tsx — el Route Handler sombreará la página, así que mantén las rutas API bajo app/api/ para evitar conflictos silenciosos.

Usa template.tsx para reiniciar por cada navegación: layout.tsx persiste a través de la navegación y su estado sobrevive a los cambios de ruta hija; cuando específicamente necesitas remontar (p. ej., reiniciar animaciones o estado en cada navegación), usa template.tsx en su lugar.

Analiza los tipos de parámetros dinámicos: Todo valor de segmento dinámico llega como una cadena — const postId = Number(params.id) — así que convierte a la forma que realmente necesitas en lugar de confiar solo en la anotación de tipo.

Usa [[...slug]] cuando la ruta base debe coincidir: Un catch-all [...path] no coincide con la ruta padre, así que /docs es 404; cambia a [[...path]] o añade un page.tsx separado junto a él cuando el segmento base debe resolver.

Deja que lo estático gane sobre lo dinámico explícitamente: Cuando las rutas estáticas y dinámicas se superponen, la estática siempre gana, así que puedes mantener un /blog/about/page.tsx junto a [slug]/page.tsx sin conflicto.

generateStaticParams se ejecuta en tiempo de compilación: La función se ejecuta durante next build, así que cualquier fuente de datos no disponible falla la compilación; combínala con dynamicParams = true cuando las nuevas rutas aún deben renderizarse en la primera solicitud.

error.tsx debe ser "use client": React Error Boundaries requieren ciclo de vida del cliente, así que cada error.tsx necesita la directiva "use client" — y solo captura errores debajo de sí, nunca en el layout.tsx hermano del mismo segmento.

global-error.tsx controla html y body: global-error.tsx reemplaza el layout raíz completo cuando se activa, así que debe renderizar su propio <html><body>; también ten en cuenta que solo se activa en producción (la superposición de desarrollo se ejecuta en desarrollo).

notFound y redirect lanzan excepciones: Ambos lanzan errores centinela de Next.js, así que un try/catch circundante los traga — llámalos fuera de try/catch, o usa unstable_rethrow en el bloque catch para dejarlos propagarse.

Reserva root not-found para rutas no coincidentes: El root not-found.tsx captura automáticamente cualquier URL que no coincida con una ruta, mientras que los archivos not-found.tsx anidados solo se activan cuando explícitamente llamas a notFound() desde dentro de ese subárbol.

Los layouts no pueden leer searchParams: Solo las pages reciben searchParams; si un layout necesita estado de URL, levanta la lógica a una page o un Client Component que usa useSearchParams() dentro de un límite Suspense.

Pasa datos vía Context, no props de layout: Los layouts no pueden reenviar props a sus hijos, así que comparte estado a través de un proveedor Client Context, cookies, o un auxiliar Server Component que vuelve a obtener en cada hijo.

Importa useRouter desde next/navigation: En el App Router, useRouter, usePathname, y useSearchParams viven en next/navigation; next/router es el Pages Router y silenciosamente falla o es 404 cuando se importa.

Envuelve useSearchParams en Suspense: useSearchParams() sin un límite <Suspense> circundante opta toda la ruta al renderizado del lado del cliente — siempre delimítalo: <Suspense fallback={null}><SearchFilters /></Suspense>.

Usa useTransition para UI pendiente: router.push() devuelve void, así que envuelve navegaciones en useTransition — startTransition(() => router.push("/dashboard")) — para obtener una bandera isPending y deshabilitar botones o mostrar spinners durante cambios de ruta.

router.refresh con alcance a la ruta actual: refresh() vuelve a obtener datos del servidor para la ruta activa solo; otras rutas cacheadas permanecen obsoletas, así que combínala con revalidateTag/revalidatePath cuando la mutación afecta hermanos.

Controla Link prefetch y scroll: <Link> prefetcha en la entrada del viewport y se desplaza hacia arriba por defecto — <Link href="/settings" prefetch={false} scroll={false}> — establece prefetch={false} en enlaces raramente usados y scroll={false} para UIs de pestaña/filtro que deben permanecer en su lugar.

Siempre establece un matcher de middleware: Sin config.matcher tu middleware se ejecuta en cada solicitud incluyendo /_next/static y favicons — export const config = { matcher: ["/dashboard/:path*", "/api/:path*"] } — define el alcance explícitamente y excluye destinos de redirección para evitar bucles infinitos.

Edge middleware prohíbe APIs Node: Middleware se ejecuta en Edge Runtime, así que bcrypt, fs, y la mayoría de drivers de base de datos se rompen en compilación o runtime — usa solo APIs Web y librerías compatibles con edge.

Devuelve NextResponse.next para continuar: NextResponse.next() no hace corto-circuito; debes return (o una redirección/reescritura) para realmente detener la cadena de middleware, de lo contrario la lógica subsecuente sigue ejecutándose.

Cada slot paralelo necesita default.tsx: Las carpetas @slot deben incluir un fallback default.tsx, de lo contrario navegaciones duras o subrutas no coincidentes son 404; los slots también deben ser hijos directos del layout y no pueden anidar dentro uno del otro.

Reserva espacio para slots independientes: Los slots de ruta paralela se resuelven independientemente, así que da a cada uno una altura fija o skeleton que coincida con el contenido final — de lo contrario streaming causa desplazamiento de layout visible mientras cada slot se rellena.

Ten en mente la convención del punto de intercepción: (.), (..), (..)(..), y (...) cuentan los segmentos de grupos de ruta igual que las carpetas regulares, así que los grupos de ruta pueden requerir un salto (..) extra; la falta de default.tsx en el slot anfitrión también rompe el cierre de back-navigation.

Los grupos de ruta no pueden colisionar: Dos carpetas (group) no pueden resolver a la misma ruta de URL (la compilación falla), y múltiples layouts raíz fuerzan una recarga de página completa entre grupos en lugar de navegación suave — mantén la ruta del inicio / en exactamente un grupo.

Mejores prácticas de enrutamiento en Next.js

Buscar en la documentación

Mejores prácticas de enrutamiento en Next.js