Trampas al actualizar a Next.js 16: valores predeterminados de rutas paralelas y middleware para proxy

La mayor parte del esfuerzo en la actualización a Next.js 16 se dedica al cambio en los parámetros async params y searchParams, ya que causa problemas graves en todas partes. Otros dos cambios relacionados con el enrutamiento, aunque menos notorios, requieren la misma atención: los espacios de ruta paralelos ahora necesitan un archivo default.js explícito, y la intercepción de solicitudes pasa de middleware.ts a una nueva convención en proxy.ts. Ninguno de estos cambios afecta las páginas que usamos a diario, y precisamente por eso pasan desapercibidos durante las pruebas. Esta guía explica ambos cambios, el motivo por el cual se detectan tarde, y ofrece una lista de verificación para realizar antes de lanzar la actualización.

Los espacios de ruta paralelos necesitan un default.js

Las rutas paralelas utilizan carpetas precedidas por @ para definir espacios con nombre que el diseño muestra uno al lado del otro. Los paneles de control son el caso típico: un área principal de contenido junto a un feed de actividades persistente o un panel de notificaciones, cada uno con su propio estado de navegación.

En Next.js 16 se espera que cada espacio tenga un archivo default.js. Ese archivo es el que Next.js muestra para un espacio cuando la URL actual no contiene una coincidencia más específica. Sin él, una navegación que lleve a dicha combinación devuelve un 404 en lugar de hacer una transición suave, y según las notas de actualización a Next.js 16, la compilación podría negarse a continuar si un espacio carece de un archivo por defecto; por lo tanto, confirme el comportamiento exacto para su versión. Un panel de control con un espacio de feed se ve así:

app/
  dashboard/
    @feed/
      page.tsx       ← the "active" state for this slot
      default.js      ← required fallback when no more-specific match exists
    layout.tsx
    page.tsx

Rara vez es necesario que el mecanismo de respaldo haga mucho. Renderizar null oculta el espacio correspondiente, y un componente de estado vacío funciona cuando se desea que el panel permanezca visible:

// app/dashboard/@feed/default.js
export default function Default() {
  return null;
}

Por qué el valor predeterminado faltante aparece tarde

Durante el desarrollo, generalmente se navega entre los estados que se han creado y probado, y todos ellos coinciden con algo en cada espacio. El problema surge cuando un usuario accede a una combinación que nadie ha probado: un enlace profundo, una actualización de página en una URL anidada, o una ruta que existe para el contenido principal pero no para el feed. Una carga completa de la página no puede reutilizar el estado anterior de un espacio, por lo que Next.js necesita default.js para saber qué renderizar. En la práctica, esto significa que el error 404 suele ser reportado por un cliente confundido en producción, en lugar de detectarse durante el desarrollo. Agregar el archivo para cada espacio, incluso cuando se cree que nunca será utilizado, es una forma económica de garantizar la solución.

De middleware.ts a proxy.ts

El segundo cambio se refiere a la intercepción a nivel de solicitud. Next.js 16 introduce proxy.ts como la convención a partir de ahora para la lógica que anteriormente se encontraba en middleware.ts, y el antiguo nombre de archivo se está eliminando gradualmente. En el momento de escribir esto, la migración implica renombrar el archivo y su función exportada; el proxy está diseñado para ejecutarse en el entorno de Node.js. Consulte la documentación actual para obtener detalles y el codemod oficial que realiza la parte técnica.

Si su middleware es sencillo, el cambio es rápido. Si realiza tareas importantes, como verificaciones de autenticación, resolución de usuarios según subdominios, redirecciones o reescritura de encabezados, considérelo como un cambio de código que requiere revisión en lugar de simplemente un renombramiento de archivo.

Revise la función por función, no solo por renombramiento

Una sustitución automática desde middleware.ts hasta proxy.ts asume que toda la lógica se comportará de manera idéntica bajo la nueva convención. En lugar de eso, analice qué hace realmente el archivo y verifique cada responsabilidad por separado:

• qué solicitudes abarca la configuración del comparador, y si se han añadido o eliminado rutas
• cómo se toman las decisiones de autenticación y qué ocurre cuando falta o ha expirado una sesión
• cómo se extraen los identificadores de inquilino de los nombres de host o encabezados y se transmiten posteriormente
• qué redirecciones y reescrituras se ejecutan, y en qué orden
• qué encabezados se leen, se añaden o se eliminan

En esta capa, una diferencia sutil en el comportamiento se convierte en un error de seguridad en lugar de uno meramente estético. Una entrada del comparador que se omita puede dejar una ruta sin autenticación; un encabezado modificado puede romper la aislamiento de los usuarios. Por eso merece una revisión cuidadosa y pruebas de extremo a extremo, y no solo verificaciones visuales rápidas.

Dos cambios no relacionados con el mismo patrón de fallo

Técnicamente, los valores predeterminados de las rutas paralelas y la migración del proxy no tienen nada que ver entre sí. Los equipos tienden a descubrirlos durante la misma actualización porque comparten un patrón: ambos funcionan en su mayoría en el entorno de desarrollo pero fallan en escenarios específicos de producción que son difíciles de reproducir.

Ese patrón merece ser nombrado. Los cambios que afectan cada carga de página se detectan en cuestión de minutos. Los riesgosos solo aparecen en rutas de navegación inusuales o con estructuras de solicitud específicas, por lo que un clic manual normal nunca los activa. Su plan de pruebas debe dirigirse intencionadamente a esas rutas.

Lista de verificación para la auditoría antes de la actualización

Antes de declarar que la actualización a Next.js 16 está completada, verifique lo siguiente:

1. Cada slot de ruta paralela cuenta con un default.js. Busque en el directorio app/ carpetas que comiencen con @ y revise cada una de ellas.
2. La lógica del middleware ha sido revisada según la convención de proxy.ts, una responsabilidad a la vez, sin renombrarla ni asumir que es idéntica.

Se han probado de extremo a extremo la autenticación y la resolución de inquilinos después de la migración, incluyendo casos negativos como sesiones ausentes o subdominios desconocidos.

Se han probado intencionadamente rutas de navegación inusuales, como enlaces profundos, actualizaciones forzadas en URLs anidadas y rutas a las que un clic normal nunca llegaría, ya que es allí donde se ocultan los errores 404 paralelos.

Por qué los paneles multiinquilino conllevan el mayor riesgo

Los paneles SaaS suelen combinar ambas características: rutas paralelas para los paneles y un middleware que asigna un subdominio a un inquilino antes de que se muestre cualquier página. Eso coloca la resolución de inquilinos directamente en el código más afectado por la transición del proxy.

Un error aquí rara vez provoca consecuencias graves. En lugar de una página de error, se reciben informes de que un inquilino vio brevemente los datos de otro, lo cual es más o menos el incidente más serio que puede ocurrir en un producto SaaS. La defensa en profundidad ayuda: incluso cuando el proxy identifica al inquilino, el acceso a los datos en los componentes del servidor y los manejadores de rutas deben verificar nuevamente la pertenencia del inquilino en lugar de confiar en los encabezados enviados desde arriba. El caché basado en etiquetas requiere la misma atención, ya que las claves de caché deben incluir al inquilino; el artículo sobre Next.js 16: uso de caché y revalidación basada en etiquetas aborda ese aspecto.

Preguntas frecuentes

¿El omitir default.js provoca un fallo silencioso?

No del todo. Se obtiene un error 404 o un error de compilación en las versiones que aplican esta regla, pero solo para las rutas de navegación que acceden al recurso de respaldo faltante. Dado que el error aparece lejos del lugar que lo causó, es fácil confundirlo con un problema general de enrutamiento a menos que se conozca este cambio.

¿Puede seguir utilizando middleware.ts por ahora?

Consulte la documentación de Next.js correspondiente a su versión específica, ya que el soporte para la antigua convención está evolucionando. Teniendo en cuenta la frecuencia con la que la autenticación se encuentra en este archivo, posponer la migración indefinidamente es más arriesgado que aplazar la mayoría de las otras tareas de actualización, y hacerlo temprano le da tiempo para una revisión adecuada.

¿Cómo encontrar rápidamente los slots sin un default.js?

Búsque carpetas dentro de app/ cuyos nombres comiencen con @ y enumere aquellas que no contengan un archivo default.js (o default.tsx). Una sola búsqueda con la función de búsqueda de archivos de su editor o un breve comando en la terminal permite encontrar todas las excepciones.

Conclusión

Los cambios en Next.js 16 que más probabilidades tienen de causar problemas no son aquellos que afectan el flujo normal de funcionamiento. Los espacios para rutas paralelas sin valor predeterminado y los proxies renombrados apresuradamente pasan las pruebas habituales pero fallan en casos extremos, a veces con consecuencias de seguridad. Añada un valor predeterminado a cada espacio, revise la lógica de intercepción caso por caso y reserve tiempo real para probar las rutas que una revisión rutinaria nunca aborda.

Lecturas relacionadas

• Una única fuente de verdad para rutas en aplicaciones Next.js — Aprenda cómo un módulo central de rutas tipado reemplaza las rutas en formato cadena dispersas en Next.js, con funciones auxiliares para segmentos dinámicos y exportaciones de rutas agrupadas.
• Migrar desde next/router: Params, URLs superficiales y errores 404 en App Router — Vea cómo funcionan params, useParams, actualizaciones de URLs superficiales, navegación programática y páginas reales de 404 en el App Router de Next.js una vez que next/router ya no está disponible.