Next.js Middleware Patterns

Next.js middleware runs before requests are completed. Here's how to use it for authentication, redirects, and more.

Basic Middleware#

// middleware.ts (in project root)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Log all requests
  console.log(`${request.method} ${request.url}`);

  // Continue with the request
  return NextResponse.next();
}

// Configure which paths middleware runs on
export const config = {
  matcher: [
    // Match all paths except static files
    '/((?!_next/static|_next/image|favicon.ico).*)',
  ],
};

Authentication Middleware#

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { verifyToken } from './lib/auth';

// Protected routes
const protectedPaths = ['/dashboard', '/settings', '/api/protected'];
const authPaths = ['/login', '/register'];

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const token = request.cookies.get('auth-token')?.value;

  // Check if path is protected
  const isProtected = protectedPaths.some((path) =>
    pathname.startsWith(path)
  );

  const isAuthPath = authPaths.some((path) =>
    pathname.startsWith(path)
  );

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

  // Redirect unauthenticated users from protected routes
  if (isProtected && !session) {
    const url = request.nextUrl.clone();
    url.pathname = '/login';
    url.searchParams.set('callbackUrl', pathname);
    return NextResponse.redirect(url);
  }

  // Redirect authenticated users from auth pages
  if (isAuthPath && session) {
    const callbackUrl = request.nextUrl.searchParams.get('callbackUrl');
    return NextResponse.redirect(
      new URL(callbackUrl || '/dashboard', request.url)
    );
  }

  // Add user info to headers for server components
  const response = NextResponse.next();
  if (session) {
    response.headers.set('x-user-id', session.userId);
  }

  return response;
}

export const config = {
  matcher: ['/dashboard/:path*', '/settings/:path*', '/login', '/register'],
};

Role-Based Access Control#

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

interface RouteConfig {
  path: string;
  roles: string[];
}

const routeConfigs: RouteConfig[] = [
  { path: '/admin', roles: ['admin'] },
  { path: '/dashboard', roles: ['admin', 'user'] },
  { path: '/api/admin', roles: ['admin'] },
];

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

  // Find matching route config
  const config = routeConfigs.find((route) =>
    pathname.startsWith(route.path)
  );

  if (!config) {
    return NextResponse.next();
  }

  // Get user session
  const token = request.cookies.get('auth-token')?.value;
  const session = token ? await verifySession(token) : null;

  if (!session) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  // Check role
  if (!config.roles.includes(session.role)) {
    return NextResponse.redirect(new URL('/unauthorized', request.url));
  }

  return NextResponse.next();
}

Geolocation and Localization#

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

const SUPPORTED_LOCALES = ['en', 'es', 'fr', 'de'];
const DEFAULT_LOCALE = 'en';

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

  // Skip if already has locale prefix
  if (SUPPORTED_LOCALES.some((locale) => pathname.startsWith(`/${locale}`))) {
    return NextResponse.next();
  }

  // Get locale from various sources
  const locale = getPreferredLocale(request);

  // Redirect to localized path
  const url = request.nextUrl.clone();
  url.pathname = `/${locale}${pathname}`;

  return NextResponse.redirect(url);
}

function getPreferredLocale(request: NextRequest): string {
  // 1. Check cookie preference
  const cookieLocale = request.cookies.get('locale')?.value;
  if (cookieLocale && SUPPORTED_LOCALES.includes(cookieLocale)) {
    return cookieLocale;
  }

  // 2. Check Accept-Language header
  const acceptLanguage = request.headers.get('accept-language');
  if (acceptLanguage) {
    const browserLocale = acceptLanguage
      .split(',')[0]
      .split('-')[0]
      .toLowerCase();

    if (SUPPORTED_LOCALES.includes(browserLocale)) {
      return browserLocale;
    }
  }

  // 3. Check geo location (Vercel)
  const country = request.geo?.country;
  if (country) {
    const countryLocale = COUNTRY_LOCALE_MAP[country];
    if (countryLocale && SUPPORTED_LOCALES.includes(countryLocale)) {
      return countryLocale;
    }
  }

  return DEFAULT_LOCALE;
}

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)'],
};

A/B Testing#

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

const EXPERIMENTS = {
  'new-homepage': {
    variants: ['control', 'variant-a', 'variant-b'],
    weights: [0.34, 0.33, 0.33],
  },
  'checkout-flow': {
    variants: ['control', 'simplified'],
    weights: [0.5, 0.5],
  },
};

export function middleware(request: NextRequest) {
  const response = NextResponse.next();

  // Assign experiments
  for (const [name, config] of Object.entries(EXPERIMENTS)) {
    const cookieName = `experiment-${name}`;
    let variant = request.cookies.get(cookieName)?.value;

    // Assign new variant if not set
    if (!variant || !config.variants.includes(variant)) {
      variant = selectVariant(config.variants, config.weights);
      response.cookies.set(cookieName, variant, {
        maxAge: 60 * 60 * 24 * 30, // 30 days
      });
    }

    // Add to headers for server components
    response.headers.set(`x-${cookieName}`, variant);
  }

  return response;
}

function selectVariant(variants: string[], weights: number[]): string {
  const random = Math.random();
  let cumulative = 0;

  for (let i = 0; i < variants.length; i++) {
    cumulative += weights[i];
    if (random < cumulative) {
      return variants[i];
    }
  }

  return variants[variants.length - 1];
}

Rate Limiting#

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

// Simple in-memory rate limiting (use Redis in production)
const rateLimit = new Map<string, { count: number; timestamp: number }>();

const RATE_LIMIT = 100; // requests
const WINDOW_MS = 60 * 1000; // 1 minute

export function middleware(request: NextRequest) {
  const ip = request.ip ?? request.headers.get('x-forwarded-for') ?? 'unknown';
  const key = `rate-limit:${ip}`;

  const now = Date.now();
  const windowStart = now - WINDOW_MS;

  // Get or create rate limit entry
  let entry = rateLimit.get(key);

  if (!entry || entry.timestamp < windowStart) {
    entry = { count: 0, timestamp: now };
  }

  entry.count++;
  rateLimit.set(key, entry);

  // Check if rate limited
  if (entry.count > RATE_LIMIT) {
    return new NextResponse('Too Many Requests', {
      status: 429,
      headers: {
        'Retry-After': String(Math.ceil((entry.timestamp + WINDOW_MS - now) / 1000)),
      },
    });
  }

  // Add rate limit headers
  const response = NextResponse.next();
  response.headers.set('X-RateLimit-Limit', String(RATE_LIMIT));
  response.headers.set('X-RateLimit-Remaining', String(RATE_LIMIT - entry.count));

  return response;
}

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

Request/Response Modification#

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

export function middleware(request: NextRequest) {
  // Clone and modify request headers
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-request-id', crypto.randomUUID());
  requestHeaders.set('x-custom-header', 'middleware-value');

  // Rewrite URL (internal redirect)
  if (request.nextUrl.pathname === '/old-path') {
    return NextResponse.rewrite(new URL('/new-path', request.url));
  }

  // Modify response
  const response = NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  });

  // Add security headers
  response.headers.set('X-Frame-Options', 'DENY');
  response.headers.set('X-Content-Type-Options', 'nosniff');
  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');

  // Set CORS headers for API routes
  if (request.nextUrl.pathname.startsWith('/api/')) {
    response.headers.set('Access-Control-Allow-Origin', '*');
    response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
  }

  return response;
}

Combining Multiple Middleware#

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

type MiddlewareFunction = (
  request: NextRequest,
  response: NextResponse
) => NextResponse | Promise<NextResponse>;

const middlewares: MiddlewareFunction[] = [
  authMiddleware,
  localeMiddleware,
  rateLimitMiddleware,
  securityHeadersMiddleware,
];

export async function middleware(request: NextRequest) {
  let response = NextResponse.next();

  for (const mw of middlewares) {
    response = await mw(request, response);

    // Stop chain if response is not NextResponse.next()
    if (response.status !== 200 || response.headers.get('x-middleware-rewrite')) {
      break;
    }
  }

  return response;
}

// Individual middleware functions
function authMiddleware(request: NextRequest, response: NextResponse) {
  // Auth logic
  return response;
}

function localeMiddleware(request: NextRequest, response: NextResponse) {
  // Locale logic
  return response;
}

Best Practices#

Performance:
✓ Keep middleware fast (runs on every request)
✓ Avoid heavy computations
✓ Use Edge runtime efficiently
✓ Cache when possible

Security:
✓ Validate tokens properly
✓ Sanitize inputs
✓ Set security headers
✓ Handle errors gracefully

Configuration:
✓ Use specific matchers
✓ Exclude static files
✓ Order middleware logically
✓ Test all paths

Next.js middleware enables powerful request-time logic including authentication, localization, A/B testing, and rate limiting. Keep middleware fast since it runs on every matched request. Use specific matchers to avoid unnecessary execution and combine multiple concerns thoughtfully.