Next.js Middleware: interceptación de peticiones y lógica en Edge

Por qué es necesario: problemática y contexto arquitectónico#

En el desarrollo de software a escala de producción, resulta crítico inspeccionar y filtrar el tráfico entrante antes de que los servidores de la aplicación consuman ciclos de CPU renderizando componentes o ejecutando costosas consultas a la base de datos:

• Protección de áreas privadas (Auth Guards): Validación centralizada de tokens de sesión sin duplicar código de autenticación en cada una de las páginas.
• Enrutamiento geográfico y localización: Detección del país, idioma y región del usuario mediante cabeceras de CDN (x-vercel-ip-country) con redirección al prefijo de idioma pertinente.
• Inyección de cabeceras de seguridad informática: Implementación centralizada de Content Security Policy (CSP) con generación de valores nonce criptográficos de un solo uso y cabeceras HSTS.
• Enrutamiento multi-inquilino (Multi-tenant) y experimentos A/B: Reenvío transparente mediante proxy de solicitudes con subdominios hacia directorios internos sin modificar la URL visible para el usuario.

Next.js da respuesta a estos requisitos mediante una pasarela especializada: Next.js Middleware. Se trata de código ejecutado en nodos de borde de la CDN (Edge Network) para cada petición HTTP entrante antes de la resolución del enrutador y la comprobación de la caché del servidor.

Modelo mental: Edge Network y canalización de ejecución#

El archivo middleware.ts se declara estrictamente en la raíz del proyecto (al mismo nivel que app o src).

El rasgo arquitectónico primordial de Middleware en Next.js es su ejecución en el Edge Runtime. Es una sandbox basada en V8 con acceso a APIs web estándar (fetch, Request, Response, Web Crypto, Headers), pero sin librerías nativas del sistema operativo de Node.js (fs, child_process, sockets TCP).

Al operar en el perímetro de la red, Middleware resuelve solicitudes en menos de 10 ms, descartando peticiones no autorizadas antes de que alcancen el centro de datos principal.

Ciclo de vida y ejecución en tiempo de ejecución (Runtime Execution)#

Sintaxis y API: contratos de Edge Runtime#

1. Estructura base y configuración de Matcher#

El archivo middleware.ts exporta una función middleware y un objeto de configuración config.matcher:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('session_token')?.value;

  // Guardia de autenticación para secciones privadas
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('from', request.nextUrl.pathname);
    return NextResponse.redirect(loginUrl);
  }

  return NextResponse.next();
}

// Configuración de rutas donde debe intervenir el Middleware
export const config = {
  matcher: [
    /*
     * Excluir recursos internos y archivos estáticos para optimizar el rendimiento:
     * - api (salvo que se requiera middleware global explícito)
     * - _next/static (archivos estáticos JS/CSS)
     * - _next/image (imágenes optimizadas)
     * - favicon.ico, sitemap.xml, robots.txt
     */
    '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

2. Modificación de cabeceras para Server Components#

Next.js permite inyectar cabeceras adicionales en la solicitud (por ejemplo, identificadores de usuario o valores nonce para CSP):

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Clonar las cabeceras de la petición entrante
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-gateway-timestamp', Date.now().toString());
  requestHeaders.set('x-client-ip', request.ip ?? 'unknown');

  // Propagar las cabeceras modificadas a los Server Components
  return NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  });
}

Patrones prácticos: organización arquitectónica#

Patrón: Enrutamiento multi-inquilino mediante rewrite#

Patrón estructural para plataformas SaaS donde el usuario accede a company.platform.com y el servidor redirige de forma transparente la solicitud hacia app/tenants/[tenant]/page.tsx:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const hostname = request.headers.get('host') ?? '';
  const pathname = request.nextUrl.pathname;

  // Extraer el subdominio del inquilino (por ejemplo, acme.platform.com -> acme)
  const currentHost = hostname.replace(`.${process.env.NEXT_PUBLIC_ROOT_DOMAIN}`, '');

  // Si se trata de un subdominio de cliente, reescribir internamente
  if (currentHost && currentHost !== 'www' && currentHost !== 'localhost:3000') {
    return NextResponse.rewrite(
      new URL(`/tenants/${currentHost}${pathname}`, request.url)
    );
  }

  return NextResponse.next();
}

Errores comunes: fallos de borde y consideraciones de diseño#

Preguntas de entrevista: Nivel Staff / Lead#