Next.js Middleware: Request Interception and Edge Logic

Why This Matters: Architectural Problem & Context#

In production web architectures, intercepting and sanitizing incoming traffic before application servers spend CPU cycles rendering React components or executing heavy database queries is paramount:

• Protected Segment Guards (Auth Guards): Centralized session token verification without duplicating authentication boilerplate across every route.
• Geographic Routing and Localization: Detecting user country, preferred language, and regional preferences via CDN headers (x-vercel-ip-country) and redirecting to the matching locale prefix.
• Security Header Injection: Enforcing strict Content Security Policy (CSP) headers with cryptographic per-request nonces and HTTP Strict Transport Security (HSTS).
• Multi-Tenant Routing and A/B Experiments: Transparently proxying subdomain requests to internal directory segments without altering the visible URL in the browser address bar.

Next.js addresses these edge gateway responsibilities using Next.js Middleware. This code executes at the distributed Edge Network layer for incoming HTTP requests prior to server cache evaluation and route tree reconciliation.

Mental Model: Edge Network and the Execution Pipeline#

The middleware.ts file must be declared strictly at the project root (adjacent to app or src).

The defining architectural characteristic of Next.js Middleware is its execution within the Edge Runtime. This is a secure V8 sandbox providing standard Web APIs (fetch, Request, Response, Web Crypto, Headers), but deliberately excluding heavy native Node.js libraries (fs, child_process, raw TCP sockets).

By executing on edge CDN nodes close to the user, Middleware evaluates requests in under 10ms, dropping unauthenticated requests before they ever reach the central origin data center.

Runtime Execution & Lifecycle#

Syntax and API: Edge Runtime Contracts#

1. Basic Structure and Matcher Configuration#

The middleware.ts file exports a middleware function alongside a config.matcher configuration object:

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

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

  // Authentication guard for protected application sections
  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();
}

// Route matching patterns where Middleware should execute
export const config = {
  matcher: [
    /*
     * Exclude internal assets and static assets for optimal performance:
     * - api (unless global middleware is explicitly needed)
     * - _next/static (static JS/CSS assets)
     * - _next/image (optimized images)
     * - favicon.ico, sitemap.xml, robots.txt
     */
    '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

2. Request Header Mutation for Server Components#

Next.js allows enriching incoming requests with downstream headers (such as injected user IDs or CSP nonces):

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

export function middleware(request: NextRequest) {
  // Clone incoming request headers
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-gateway-timestamp', Date.now().toString());
  requestHeaders.set('x-client-ip', request.ip ?? 'unknown');

  // Forward mutated headers to downstream Server Components
  return NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  });
}

Practical Architectural Patterns#

Pattern: Multi-Tenant Subdomain Routing via rewrite#

A core architectural pattern for multi-tenant SaaS platforms where visitors navigate to company.platform.com while the server internally maps the request to 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;

  // Extract tenant subdomain (e.g., acme.platform.com -> acme)
  const currentHost = hostname.replace(`.${process.env.NEXT_PUBLIC_ROOT_DOMAIN}`, '');

  // If this is a tenant subdomain, proxy internally
  if (currentHost && currentHost !== 'www' && currentHost !== 'localhost:3000') {
    return NextResponse.rewrite(
      new URL(`/tenants/${currentHost}${pathname}`, request.url)
    );
  }

  return NextResponse.next();
}

Common Pitfalls & Edge Cases#

Senior / Staff Engineering Interview Q&A#