Ejemplos de middleware de Next.js, actualizados a proxy.ts

Ejemplos de middleware (proxy) de Next.js

Ejemplos de middleware de Next.js (ahora proxy.ts): auth, geo, A/B | We.Inc

Ejemplos funcionales de proxy.ts para Next.js 16, el archivo que sustituyó a middleware.ts: redirecciones de autenticación, rutas por país, cookies A/B, detección de idioma, matchers y un simulador.

En Next.js 16 el archivo de middleware pasa a ser proxy.ts y exporta una función llamada proxy; middleware.ts está obsoleto y un codemod lo renombra. La función recibe un NextRequest y puede redirigir, reescribir, definir cabeceras o cookies, o devolver una respuesta. Un config.matcher limita las rutas en las que se ejecuta. Ahora usa el runtime de Node.js por defecto.

Qué cambió en Next.js 16

Antes (15 y anteriores)
Ahora (16)

proxy.ts, al mismo nivel que app o pages

export function middleware()
export function proxy() o una exportación por defecto

Runtime Edge por defecto
Runtime de Node.js por defecto; la opción runtime lanza un error

skipMiddlewareUrlNormalize
skipProxyUrlNormalize

Renombrado manual
npx @next/codemod@canary middleware-to-proxy .

Muchas respuestas en internet siguen describiendo middleware.ts con el runtime Edge. Los ejemplos de aquí usan el nombre de archivo actual, funcionan tal como están escritos y son lo bastante cortos para adaptarlos. Prueba el simulador para ver qué rama de un proxy combinado se activa con una solicitud concreta antes de desplegarlo.

Elige una ruta y define las cookies, el país y el idioma que lleva la solicitud de prueba.
El simulador aplica, en tu navegador, los ejemplos de autenticación, país, A/B e idioma que aparecen más abajo, en ese orden.
Lee el resultado: dejar pasar, redirigir a una nueva URL o reescribir a una ruta oculta.
Copia el ejemplo que se ajuste a tu caso y adapta las rutas.

Sin un matcher, proxy se ejecuta en cada solicitud, incluidos los archivos _next/static y las imágenes. Exclúyelos o una redirección de inicio de sesión puede bloquear tu CSS.
Los valores del matcher deben ser constantes; la documentación dice que las variables se ignoran porque el matcher se lee en tiempo de compilación.
Mantén optimistas las comprobaciones de proxy. Lee una cookie, redirige si falta y haz la comprobación real de permisos junto a tus datos.
Para pasar datos a la página, define una cabecera de solicitud con NextResponse.next({ request: { headers } }). Si pasas las cabeceras en el nivel superior, se envían al navegador.
El helper experimental unstable_doesProxyMatch de next/experimental/testing/server te permite hacer tests unitarios de un matcher.

Preguntas frecuentes

¿El middleware de Next.js está obsoleto?

El nombre sí. La versión 16 declara obsoleta la convención del archivo middleware y la renombra a proxy, con las mismas APIs de solicitud y respuesta. Se espera que los archivos middleware.ts antiguos migren, y el codemod oficial renombra tanto el archivo como la función exportada.

¿Por qué se renombró a proxy?

El equipo de Next.js dice que la palabra middleware se confundía con el middleware de Express y animaba a abusar de él. Proxy describe una frontera de red delante de la aplicación, y lo recomiendan como último recurso cuando ninguna otra API encaja.

¿Puedo usar el runtime Edge en proxy.ts?

No. Proxy usa Node.js por defecto, y definir la opción de segmento runtime en un archivo proxy lanza un error. Eso también significa que ahora funcionan allí las librerías exclusivas de Node, algo de lo que se quejaba mucha gente con el antiguo middleware solo para Edge.

¿La autenticación debe ir en proxy?

Solo como primer filtro. La guía de autenticación de Next.js recomienda leer la cookie de sesión en proxy para redirigir rápido y después verificar la sesión otra vez en una capa de acceso a datos, en las Server Actions y en los Route Handlers. Las Server Functions excluidas por el matcher se saltan proxy por completo.

¿Proxy funciona con la exportación estática?

No. La tabla de plataformas de la documentación indica que la exportación estática no es compatible, porque no hay servidor que lo ejecute. Los servidores Node y Docker sí son compatibles, y en otros hostings depende de su adaptador.

Dónde se sitúa proxy en la solicitud

Next.js aplica primero las cabeceras y redirecciones de next.config, después ejecuta proxy, luego las reescrituras beforeFiles y por último los archivos y rutas reales. Por tanto, una redirección en next.config gana antes de que tu código de proxy llegue a ver la solicitud.
Proxy puede terminar la solicitud por sí mismo, devolviendo una redirección o una respuesta JSON, o dejar que continúe con NextResponse.next() añadiendo cabeceras y cookies por el camino.

Redirigir o reescribir

Una redirección cambia la barra de direcciones y le cuesta al visitante un viaje de ida y vuelta extra. Úsala cuando la propia URL deba cambiar, como al enviar a /login a los usuarios sin sesión.
Una reescritura sirve otra ruta mientras la barra de direcciones se queda igual. Es adecuada para pruebas A/B y variantes por país, cuando quieres que ambas versiones compartan una misma URL pública.

Que salga barato

Proxy puede ejecutarse tanto en las precargas como en las visitas a páginas, así que las llamadas a la base de datos aquí se multiplican rápido. Leer cookies y cabeceras es barato; consultar una tabla de usuarios en cada solicitud no lo es.
El trabajo en segundo plano, como el registro de logs, puede ir en event.waitUntil(), que mantiene viva la invocación después de enviar la respuesta.

Patrones de matcher

Cómo se comportan las rutas de config.matcher

Patrón
Coincide con
No coincide con

Todas las páginas
Rutas de API, recursos de compilación, el favicon

Ejemplos de proxy.ts

Redirigir a los visitantes sin sesión

Una comprobación optimista: solo busca la cookie de sesión y recuerda adónde iba el visitante.

Rutas por país con una reescritura

El visitante mantiene la URL /pricing pero ve la página de la UE. La cabecera de país que se muestra aquí es la que añade Vercel; otros hostings usan su propio nombre de cabecera.

Prueba A/B con una cookie persistente

A cada visitante se le asigna un grupo una sola vez, la cookie lo mantiene en él y una reescritura sirve la variante en la misma URL.

Enviar a los visitantes a su idioma

Las rutas que ya empiezan con un locale compatible pasan sin cambios. Todo lo demás se redirige según la primera entrada de Accept-Language que coincida.

Pasar un valor a la página mediante una cabecera de solicitud

Definir las cabeceras dentro de la opción request permite leerlas con headers() en la ruta, sin exponerlas al navegador.

Ejemplo de autenticación: ruta protegida y sin cookie de sesión.

Ejemplo de país: {country} está en la lista de la UE, así que se sirve la página de la UE en la misma URL.

Ejemplo A/B: el visitante está en el grupo {bucket} y una cookie lo mantiene ahí.

Excluida por el matcher de idioma, así que la solicitud continúa sin cambios.

Ejemplo de idioma: la ruta ya tiene un locale compatible.

Ejemplo de idioma: el primer idioma compatible de la cabecera es {locale}.

Simulador de proxy

Define una ruta, una cookie de sesión, un país y un idioma del navegador, y mira si los ejemplos de abajo dejarían pasar la solicitud, la redirigirían o la reescribirían.

Ruta de la solicitud

Cabecera de país (x-vercel-ip-country)

Cabecera Accept-Language

Grupo de la cookie A/B

La solicitud tiene una cookie de sesión

Empieza gratis · Sin tarjeta de crédito