middleware.js

El archivo middleware.js|ts se utiliza para escribir Middleware y ejecutar código en el servidor antes de que se complete una solicitud. Luego, basándose en la solicitud entrante, puedes modificar la respuesta reescribiéndola, redirigiendo, modificando los encabezados de la solicitud o respuesta, o respondiendo directamente.

El Middleware se ejecuta antes de que se rendericen las rutas. Es particularmente útil para implementar lógica personalizada del lado del servidor como autenticación, registro de logs o manejo de redirecciones.

Utiliza el archivo middleware.ts (o .js) en la raíz de tu proyecto para definir Middleware. Por ejemplo, al mismo nivel que app o pages, o dentro de src si es aplicable.

import { NextResponse, NextRequest } from 'next/server'

// Esta función puede marcarse como `async` si se usa `await` dentro
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}

Exportaciones

Función Middleware

El archivo debe exportar una única función, ya sea como exportación por defecto o nombrada como middleware. Ten en cuenta que no se admiten múltiples middleware desde el mismo archivo.

// Ejemplo de exportación por defecto
export default function middleware(request) {
  // Lógica del Middleware
}

Objeto config (opcional)

Opcionalmente, se puede exportar un objeto config junto con la función Middleware. Este objeto incluye el matcher para especificar las rutas donde aplica el Middleware.

Matcher

La opción matcher te permite seleccionar rutas específicas donde se ejecutará el Middleware. Puedes especificar estas rutas de varias formas:

• Para una sola ruta: Usa directamente una cadena para definir la ruta, como '/about'.
• Para múltiples rutas: Usa un array para listar varias rutas, como matcher: ['/about', '/contact'], lo que aplica el Middleware tanto a /about como a /contact.

Además, matcher admite especificaciones de rutas complejas mediante expresiones regulares, como matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)'], permitiendo un control preciso sobre qué rutas incluir o excluir.

La opción matcher también acepta un array de objetos con las siguientes claves:

• source: La ruta o patrón utilizado para coincidir con las rutas de solicitud. Puede ser una cadena para coincidencia directa de rutas o un patrón para coincidencias más complejas.
• regexp (opcional): Una cadena de expresión regular que ajusta la coincidencia basada en el source. Proporciona control adicional sobre qué rutas se incluyen o excluyen.
• locale (opcional): Un booleano que, cuando se establece en false, ignora el enrutamiento basado en locale en la coincidencia de rutas.
• has (opcional): Especifica condiciones basadas en la presencia de elementos específicos de la solicitud como encabezados, parámetros de consulta o cookies.
• missing (opcional): Se centra en condiciones donde faltan ciertos elementos de la solicitud, como encabezados o cookies.

export const config = {
  matcher: [
    {
      source: '/api/*',
      regexp: '^/api/(.*)',
      locale: false,
      has: [
        { type: 'header', key: 'Authorization', value: 'Bearer Token' },
        { type: 'query', key: 'userId', value: '123' },
      ],
      missing: [{ type: 'cookie', key: 'session', value: 'active' }],
    },
  ],
}

Parámetros

request

Al definir Middleware, la función de exportación por defecto acepta un único parámetro, request. Este parámetro es una instancia de NextRequest, que representa la solicitud HTTP entrante.

import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // La lógica del Middleware va aquí
}

Nota importante:

• NextRequest es un tipo que representa solicitudes HTTP entrantes en Middleware de Next.js, mientras que NextResponse es una clase utilizada para manipular y enviar respuestas HTTP.

NextResponse

El Middleware puede utilizar el objeto NextResponse que extiende la API Web Response. Al devolver un objeto NextResponse, puedes manipular directamente cookies, establecer encabezados, implementar redirecciones y reescribir rutas.

Nota importante: Para redirecciones, también puedes usar Response.redirect en lugar de NextResponse.redirect.

Runtime

El Middleware utiliza Edge runtime por defecto. Si no deseas esto, puedes usar el runtime completo de Node.js para ejecutar Middleware.

Historial de versiones