What is Next.js Middleware? Where does it run, and what can it do that API routes cannot?

Question

Accepted Answer

Middleware sits between the incoming request and your application. It runs on every matched request before Next.js resolves which page or route handler to serve. Because it runs at the Edge — on Vercel's global edge network or a Node.js edge-compatible runtime — it executes with extremely low latency, often before the request ever reaches your server. This makes it the perfect place for auth checks, redirects, rewrites, locale detection, A/B testing, and bot protection. Runs at the Edge Runtime — NOT in the Node.js server runtime by default Executes BEFORE the request reaches pages, layouts, or route handlers Runs on every request that matches the middleware matcher config On Vercel — runs on the global edge network closest to the user Self-hosted — runs in a lightweight V8 isolate before the Next.js server Executes after the cache check — cached responses bypass middleware // middleware.js — must be in the ROOT of the project (not inside /app or /pages)
import { NextResponse } from 'next/server'

export function middleware(request) {
  const { pathname, searchParams } = request.nextUrl

console.log('Middleware running for:', pathname)
  // Runs BEFORE the page or route handler is called

// Option 1 — continue to the requested route
  return NextResponse.next()

// Option 2 — redirect to another route
  // return NextResponse.redirect(new URL('/login', request.url))

// Option 3 — rewrite (change what renders, URL stays the same)
  // return NextResponse.rewrite(new URL('/dashboard', request.url))

// Option 4 — return a response directly (short-circuit)
  // return new NextResponse('Unauthorized', { status: 401 })
}

// ✅ Control which routes middleware runs on
export const config = {
  matcher: [
    '/dashboard/:path*',
    '/admin/:path*',
    '/api/:path*'
  ]
} // middleware.js
import { NextResponse } from 'next/server'
import { verifyToken }  from '@/lib/auth'

const PROTECTED_ROUTES = ['/dashboard', '/admin', '/profile']
const AUTH_ROUTES      = ['/login', '/register']

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

const isProtected = PROTECTED_ROUTES.some(r => pathname.startsWith(r))
  const isAuthRoute  = AUTH_ROUTES.some(r => pathname.startsWith(r))

// ✅ Redirect unauthenticated users away from protected routes
  if (isProtected && !token) {
    const loginUrl = new URL('/login', request.url)
    loginUrl.searchParams.set('from', pathname) // preserve intended destination
    return NextResponse.redirect(loginUrl)
  }

// ✅ Redirect authenticated users away from login/register
  if (isAuthRoute && token) {
    return NextResponse.redirect(new URL('/dashboard', request.url))
  }

return NextResponse.next()
}

export const config = {
  matcher: [
    '/dashboard/:path*',
    '/admin/:path*',
    '/profile/:path*',
    '/login',
    '/register'
  ]
} // middleware.js
import { NextResponse } from 'next/server'

export function middleware(request) {
  const { pathname } = request.nextUrl
  const country = request.geo?.country ?? 'US'

// ✅ Geo-based rewrite — URL stays /pricing but content changes
  if (pathname === '/pricing') {
    return NextResponse.rewrite(
      new URL(`/pricing/${country.toLowerCase()}`, request.url)
    )
    // Browser sees: /pricing
    // Next.js renders: /pricing/gb or /pricing/us etc.
  }

// ✅ A/B testing rewrite — same URL, different page variant
  if (pathname === '/home') {
    const bucket = request.cookies.get('ab-bucket')?.value ?? 'a'
    return NextResponse.rewrite(
      new URL(`/home-${bucket}`, request.url)
    )
    // Browser sees: /home
    // Next.js renders: /home-a or /home-b
  }

return NextResponse.next()
} // middleware.js
import { NextResponse } from 'next/server'

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

// ✅ Add custom headers to the REQUEST (visible to route handlers)
  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-user-id', getUserIdFromToken(request))
  requestHeaders.set('x-pathname', request.nextUrl.pathname)

// ✅ Add security headers to the RESPONSE (visible to browser)
  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')
  response.headers.set('Permissions-Policy',         'camera=(), microphone=()')
  response.headers.set(
    'Content-Security-Policy',
    "default-src 'self'; script-src 'self' 'unsafe-eval'"
  )

return NextResponse.next({
    request: { headers: requestHeaders } // ✅ forward modified request headers
  })
}

// Reading middleware-set header in a Route Handler or Server Component
// import { headers } from 'next/headers'
// const userId = headers().get('x-user-id') // middleware.js
import { NextResponse } from 'next/server'

const LOCALES         = ['en', 'fr', 'de', 'es']
const D

What is Next.js Middleware? Where does it run, and what can it do that API routes cannot?

What is Next.js Middleware? Where does it run, and what can it do that API routes cannot?

Scenario Questions

Follow-up Questions