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, puede modificar la respuesta reescribiendo, redirigiendo, modificando los encabezados de 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.

Utilice el archivo middleware.ts (o .js) en la raíz de su 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*',
}

import { NextResponse } from 'next/server'

// Esta función puede marcarse como `async` si se usa `await` dentro
export function middleware(request) {
  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. Tenga 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 de configuración (opcional)

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

Matcher

La opción matcher le permite seleccionar rutas específicas donde se ejecutará el Middleware. Puede especificar estas rutas de varias maneras:

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

Además, matcher soporta 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 origen. 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 enfoca en condiciones donde ciertos elementos de la solicitud están ausentes, como encabezados o cookies faltantes.

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í
}

export function middleware(request) {
  // 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 de Respuesta Web. Al devolver un objeto NextResponse, puede manipular directamente cookies, establecer encabezados, implementar redirecciones y reescribir rutas.

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

Entorno de ejecución

El Middleware solo soporta el entorno de ejecución Edge. No se puede utilizar el entorno de ejecución Node.js.

Historial de versiones