Middleware

🔍 What Is It?

Next.js Middleware is a function exported from middleware.ts at the project root:

• →Runs on every request before it reaches a page or Route Handler
• →Edge Runtime — runs at CDN edge nodes globally (not Node.js)
• →Can read and modify request headers, cookies, and URL
• →Can redirect or rewrite requests
• →Cannot access the filesystem, Node.js APIs, or most npm packages
• →Matcher config controls which routes trigger middleware

🎯 Why Do We Need It?

Middleware solves problems that cannot be solved in layouts or pages:

• →Fast auth redirects — redirect unauthenticated users before the page even loads
• →A/B testing — rewrite requests to different pages based on a cookie
• →Geolocation — redirect users to regional versions based on their country
• →Request enrichment — add user ID to headers so all downstream components can read it
• →Bot protection — block or challenge suspicious requests at the edge

🏗️ What Happens in Real Projects?

Middleware in production:

• →Auth: verify JWT, redirect to /login if invalid
• →Internationalisation: detect locale, rewrite to /en/ or /fr/
• →Feature flags: rewrite to /beta/ for users with the beta cookie
• →Rate limiting: count requests per IP at the edge
• →Security headers: add CSP, HSTS, X-Frame-Options to all responses

⚙️ How It Works

Middleware execution flow:

1. Request arrives at CDN edge
2. Middleware function runs (Edge Runtime, ~1ms)
3. Middleware can: redirect, rewrite, modify headers, or pass through
4. If passing through: request continues to Next.js server
5. Server Component / Route Handler runs

The matcher config tells Next.js which paths trigger middleware. Without a matcher, middleware runs on EVERY request — including static files and images, which is expensive.

💻 Example

Auth Middleware and Request Enrichment — Production middleware for auth protection and request header enrichment.

// middleware.ts (project root)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { verifyJWT } from '@/lib/auth-edge'; // Must be edge-compatible

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Get session token from cookie
  const token = request.cookies.get('session')?.value;

  // Verify token
  const session = token ? await verifyJWT(token) : null;

  // Protect dashboard routes
  if (pathname.startsWith('/dashboard') || pathname.startsWith('/settings')) {
    if (!session) {
      const loginUrl = new URL('/login', request.url);
      loginUrl.searchParams.set('callbackUrl', pathname);
      return NextResponse.redirect(loginUrl);
    }
  }

  // Redirect authenticated users away from auth pages
  if (pathname.startsWith('/login') || pathname.startsWith('/register')) {
    if (session) {
      return NextResponse.redirect(new URL('/dashboard', request.url));
    }
  }

  // Pass through with user ID in header (available in Server Components)
  const response = NextResponse.next();
  if (session) {
    response.headers.set('x-user-id', session.userId);
  }
  return response;
}

// IMPORTANT: Always add a matcher to avoid running on static files
export const config = {
  matcher: [
    // Match all paths EXCEPT:
    '/((?!_next/static|_next/image|favicon.ico|.*\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
};

🤔 Common Confusions

🚨 Common Production Issues

✅ Best Practices

🏛️ Architect's Note

💬 Frequently Asked Questions

🎯 Key Takeaways

🔗 Related Topics

🎯 Practice this topic in interviews

↗ Where this topic fits